LLM과 가상 현실(VR) 통합: 단계별 가이드

우리는 텍스트 프롬프트를 대화형 A-Frame 장면으로 변환하는 VR 월드 생성기를 구축할 것입니다. FastAPI 백엔드는 Oxlo.ai를 호출하여 3D 마크업(markup)과 분위기 있는 내레이션(narration)을 생성하고, 경량 프론트엔드는 이를 브라우저에서 렌더링합니다. 이는 가상 환경의 빠른 프로토타이핑(prototyping), 대화형 스토리텔링, 또는 개발자가 아닌 사용자가 공간 경험을 생성해야 하는 모든 애플리케이션에 유용합니다.

필요한 사항

시작하기 전에 Python 3.10 이상이 설치되어 있는지 확인하세요. 또한 https://portal.oxlo.ai에서 발급받은 Oxlo.ai API 키와 OpenAI SDK가 필요합니다. Oxlo.ai는 요청 기반 요금제(request-based pricing)를 사용하므로, 긴 장면 설명이나 다회차 컨텍스트(multi-turn context)를 보내더라도 토큰 기반 과금 방식처럼 비용이 급격히 증가하지 않습니다. 자세한 내용은 https://oxlo.ai/pricing을 참조하세요.

Python 3.10+
pip install openai fastapi uvicorn
Oxlo.ai API 키
WebGL을 지원하는 최신 웹 브라우저

1. Oxlo.ai 클라이언트 설정

먼저, Oxlo.ai에 접속할 수 있는지와 일관된 장면 설명을 가져올 수 있는지 확인합니다. vr_builder.py를 생성하고 Oxlo.ai를 가리키는 OpenAI 호환 클라이언트를 초기화합니다.

from openai import OpenAI

client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
...

2. 시스템 프롬프트 및 장면 생성기 정의

이제 출력 형식을 고정합니다. 모델은 A-Frame 장면 마크업(markup), 내레이션 문자열, 그리고 대화형 객체 ID 목록을 포함하는 유효한 JSON을 반환해야 합니다. 나머지 로직을 건드리지 않고도 수정할 수 있도록 시스템 프롬프트(system prompt)를 상수로 정의합니다.

SYSTEM_PROMPT = """당신은 VR 월드 빌더 (VR world builder)입니다. 사용자의 설명을 바탕으로 정확히 세 개의 키를 가진 JSON 객체를 생성하세요:
- "scene_html": 완전한 A-Frame <a-scene> 요소를 포함하는 문자열입니다. 하늘(sky), 지면(ground plane), 조명(lighting), 그리고 최소 세 개의 상호작용 가능한 객체(interactive objects)를 포함해야 합니다. 모든 상호작용 가능한 객체는 고유한 id와 class="clickable"을 가져야 합니다. 표준 A-Frame 프리미티브(primitives)만 사용하세요.
- "narration": 사용자에게 표시할 짧고 분위기 있는 내레이션(narration)입니다.
...
"""

그 다음, Oxlo.ai를 호출하고 결과를 파싱하는 재사용 가능한 함수로 이를 연결합니다.

import json
from openai import OpenAI

...

3. FastAPI 백엔드 구축

다음으로, 생성기(generator)를 FastAPI 애플리케이션으로 감쌉니다. /generate 엔드포인트(endpoint)는 프롬프트(prompt)를 받아 Oxlo.ai를 호출하고 파싱된 장면 데이터를 반환합니다. 로컬 개발 중에 프론트엔드(frontend)가 접근할 수 있도록 CORS를 추가합니다.

import json
from openai import OpenAI
from fastapi import FastAPI
...

4. A-Frame 프론트엔드 생성

프론트엔드는 VR 장면을 위한 iframe을 호스팅하는 단일 HTML 파일입니다. 사용자의 프롬프트를 FastAPI 백엔드로 POST 요청하고, 반환된 HTML을 srcdoc을 사용하여 iframe에 주입합니다. 이렇게 하면 생성된 월드가 격리되어 A-Frame DOM 병합 문제를 방지할 수 있습니다.

<!DOCTYPE html>
<html lang="ko">
<head>
...

5. 동적 객체 상호작용 추가

정적인 장면은 이야기의 절반에 불과합니다. 사용자가 객체를 클릭하면 AI가 생성한 설정(lore)을 받을 수 있기를 원합니다. 창의적 추론(creative reasoning)을 위해 qwen-3-32b를 사용하는 /interact 엔드포인트를 추가하고, 각 객체에 대한 버튼을 노출합니다. 버튼을 클릭하면 프론트엔드가 iframe DOM을 직접 조작하여 즉각적인 시각적 피드백을 제공합니다.

uvicorn 블록 이전에 vr_builder.py에 새로운 엔드포인트를 추가하세요.

class InteractRequest(BaseModel):
    object_id: str
    scene_context: str
...

그 다음, 각 생성 후에 상호작용 버튼을 렌더링하도록 프론트엔드를 확장합니다.

    async function generate() {
      const user_message = document.getElementById('prompt').value;
      const res = await fetch('http://localhost:8000/generate', {
...```

## 실행하기 (Run it)

터미널에서 백엔드를 시작하세요.

python vr_builder.py


브라우저에서 `index.html`을 열거나, `python -m http.server 8080`으로 서버를 실행한 후 `http://localhost:8080`에 접속하세요. 프롬프트를 입력하고 'Generate World'를 클릭합니다. iframe 내에 A-Frame 장면(scene)이 로드되면서 내레이션(narration) 라인이 함께 나타나는 것을 확인할 수 있습니다. 'Generate World'를 클릭한 후의 출력 예시는 다음과 같습니다:

{
"scene_html": "<a-scene>\n <a-sky color="#050510"></a-sky>\n <a-plane position="0 0 -4" rotation="-90 0 0" width="20" height="20" color="#222"></a-plane>\n <a-box id="crate" class="clickable" position="-1 0.5 -3" color="#654321"></a-box>\n <a-sphere id="orb" class="clickable" position="1 1 -3" color="#00ffcc"></a-sphere>\n <a-cylinder id="pillar" class="clickable" position="0 1 -4" radius="0.3" height="2" color="#777"></a-cylinder>\n <a-light type="ambient" color="#444"></a-light>\n <a-light type="point" position="2 3 2" color="#ffaa00"></a-light>\n</a-scene>",
"narration": "The alley hums with hidden current. Three artifacts await your attention.",
...


orb 버튼을 클릭하면 다음과 같은 결과가 반환될 수 있습니다:

{
"lore": "The orb pulses with a frequency that predates the city above.",
"effect": "glow"
...


## 다음 단계 (Next steps)

마이크 오디오를 Oxlo.ai의 Whisper 엔드포인트(endpoint)로 전달하여 텍스트 버튼을 음성 입력으로 교체하고, Kokoro TTS로 응답을 합성하면 완전히 핸즈프리(hands-free)인 VR 인터페이스를 구축할 수 있습니다. 만약 세션 전반에 걸쳐 세계의 상태를 기억하게 하고 싶다면, Oxlo.ai의 BGE-Large 엔드포인트를 사용하여 객체 임베딩(embeddings)을 저장하고, 로드할 때마다 이를 검색하여 지속적인 서사 메모리(persistent narrative memory)를 구축하세요.

Insights

LLM과 가상 현실(VR) 통합: 단계별 가이드

요약

핵심 포인트