AKOOL의 스트리밍 아바타 SDK는 이미 실시간 비디오, 오디오, 텍스트 및 마이크 상호작용을 위한 기반을 제공합니다. 다음 단계는 신뢰할 수 있는 제품 문서, 정책, 교육 자료 또는 지원 콘텐츠를 아바타에 연결하여 비즈니스에 활용하는 것입니다.
이 가이드는 지식 계층에 중점을 둡니다. AKOOL 지식 베이스를 생성하고 이를 스트리밍 아바타 세션에 연결하여 knowledge_id를 설정한 다음, 아바타가 애플리케이션 내에서 정확한 답변을 제공하는지 확인하게 됩니다.
공식 SDK 문서에서는 아바타를 스트리밍하는 방법을 설명합니다. 이 가이드에서는 아바타가 귀사의 비즈니스를 이해하도록 만드는 방법을 안내합니다.
구축할 내용
완성된 환경은 세 가지 요소로 구성됩니다. 승인된 지식 소스, 해당 소스를 대화용으로 준비하는 AKOOL 지식 베이스, 그리고 애플리케이션에 내장된 스트리밍 아바타입니다. 사용자가 질문하면 아바타는 연결된 지식 베이스를 문맥으로 활용하여 동기화된 음성과 비디오를 통해 답변을 반환합니다.
지식 계층과 라이브 세션 간의 연결은 knowledge_id 필드입니다. 이 필드는 브라우저가 실시간 채널에 참여하기 전, 스트리밍 아바타 세션이 생성될 때 추가됩니다.
지식 소스는 AKOOL 내에서 처리되며 knowledge_id로 표시됩니다. 백엔드에서 스트리밍 아바타 세션을 생성할 때 이 ID를 포함하십시오. 그러면 브라우저가 AKOOL SDK를 통해 반환된 세션에 참여하게 되며, 서버의 자격 증명을 안전하게 유지하면서 아바타가 승인된 지식을 바탕으로 답변할 수 있게 됩니다.
구축 경로 선택
빠르게 작동하는 프로토타입을 원하신다면 아래 프롬프트를 AI 코딩 에이전트에 복사하세요. 이미 AKOOL 스트리밍 아바타 통합을 완료했거나 워크플로를 직접 구성하고 싶다면 퀵 스타트를 계속 진행하세요. 두 경로 모두 동일한 결과, 즉 귀사의 콘텐츠를 기반으로 답변하는 라이브 아바타를 생성합니다.
옵션 1: AI 에이전트로 구축하기
이 프롬프트를 선호하는 AI 코딩 에이전트에 복사하고 요청 시 AKOOL 구성을 제공하세요.
AI 에이전트 구축 프롬프트
Build a knowledge-powered AKOOL Streaming Avatar application.
Use AKOOL’s official Streaming Avatar SDK Quick Start as the implementation reference:
https://docs.akool.com/sdk/jssdk-start
Start from the official SDK workflow instead of recreating a generic streaming demo. Add the following knowledge-base workflow:
1. Create the avatar session from a backend endpoint.
2. Read the Avatar ID, Knowledge Base ID, optional Voice ID, language, and duration from server-side configuration.
3. Include knowledge_id and mode_type: 2 in the session-creation request.
4. Return only the temporary session credentials required by the browser.
5. Use the official AKOOL JavaScript SDK for video, audio, text, microphone, and interruption controls.
6. Add an explicit End Session action.
7. Provide a small test panel for an exact-source question, a paraphrased question, and an out-of-scope question.
Keep the interface simple and use the linked AKOOL documentation as the source of truth.옵션 2: 퀵 스타트 따라하기
기존 애플리케이션에 지식 계층을 추가하거나 AI 에이전트에 작업을 맡기기 전에 통합 과정을 이해하고 싶을 때 이 경로를 사용하세요.
시작하기 전에
API 액세스가 가능한 AKOOL 계정, 스트리밍 아바타 ID, 그리고 공식 JavaScript SDK를 기반으로 작동하는 스트리밍 아바타 애플리케이션이 필요합니다. 다음을 수행할 수 있습니다. AKOOL에서 스트리밍 아바타 생성 또는 관리하기아바타가 사용할 문서나 공개 URL을 준비하세요. Voice ID는 선택 사항입니다.
아직 스트리밍 아바타에 연결하지 않았다면 먼저 스트리밍 아바타 SDK 퀵 스타트 를 완료하세요. 이 문서에서는 설치, 채널 연결 또는 미디어 처리 단계에 대해 반복적으로 설명하지 않습니다.
1단계: 지식 소스 준비하기
지원되는 문서를 업로드하거나 공개 URL을 추가하세요. 첫 테스트를 간단하게 시작하려면 깔끔하고 잘 구성된 DOCX 파일이 좋습니다. 지식 베이스가 올바른 구절을 안정적으로 검색할 수 있도록 각 소스는 하나의 주제에 집중하게 하세요.
작고 신뢰할 수 있는 소스 세트와 좁은 테스트 범위로 시작하세요. 첫 질문에 정확한 답변이 나오면, 문서나 URL을 단계적으로 추가하며 다시 테스트하세요.
2단계: AKOOL 지식 베이스 생성하기
핵심 설정 필드를 작성하세요: 명확한 이름, 시작 멘트(API의prologue ), 지침 프롬프트, 그리고 AKOOL이 소스로 사용할 문서나 공개 URL을 입력합니다.
시작 멘트(prologue): 세션이 시작될 때 아바타가 할 첫 메시지를 작성하세요. 짧고 환영하는 느낌을 주며 지식 베이스 범위에 맞게 작성하는 것이 좋습니다.
프롬프트: "승인된 지식 소스를 사용하여 질문에 답변하세요. 간결하고 도움이 되는 답변을 제공하세요. 정보가 없는 경우, 이를 명확히 밝히고 다음 지원 단계를 제안하세요."
소스 처리가 완료될 때까지 기다린 후 지식 베이스 ID를 복사하세요. AKOOL은 이 값을 라이브 세션의 knowledge_id 로 사용합니다.
3단계: 지식 베이스를 세션에 연결하기
백엔드에서 스트리밍 아바타 세션을 생성할 때 요청에 지식 베이스 ID를 추가하세요. 아바타가 질문에 답변하고 대화를 이어갈 수 있도록 대화 모드를 사용하세요.
세션 구성 예시
{
"avatar_id": "your_avatar_id",
"voice_id": "your_voice_id",
"knowledge_id": "your_knowledge_id",
"mode_type": 2
}중요한 세부 사항은 이 작업이 수행되는 시점입니다. knowledge_id 은 브라우저의 joinChat() 호출이 아닌 세션 생성 단계에 포함되어야 합니다. 세션이 생성되면 브라우저는 AKOOL에서 반환된 임시 자격 증명을 사용하여 연결하고 표준 SDK 상호작용 흐름을 사용할 수 있습니다.
API 키를 비공개로 유지하기 위해 브라우저에서 직접 생성하지 말고 백엔드에서 세션을 생성하세요. 이 cURL 예시는 세션 생성 시 지식 베이스 ID를 전송하고 다음을 통해 대화 모드를 활성화합니다. mode_type: 2.
지식 베이스 기반 스트리밍 아바타 세션 생성하기
curl --request POST \
--url https://openapi.akool.com/api/open/v4/liveAvatar/session/create \
--header "Content-Type: application/json" \
--header "x-api-key: <api-key>" \
--data '{
"avatar_id": "<avatar-id>",
"voice_id": "<voice-id>",
"language": "en",
"duration": 600,
"mode_type": 2,
"knowledge_id": "<knowledge-id>",
"stream_type": "agora"
}'반환된 세션 자격 증명을 서버에 저장하고, 필요한 연결 값만 클라이언트에 전달하여 AKOOL 스트리밍 아바타 SDK를 초기화하는 데 사용하세요.
4단계: 애플리케이션에 아바타 추가하기
AKOOL JavaScript SDK를 사용하여 실시간 채널에 참여하고, 대화 모드로 채팅을 시작하며, 원격 비디오 및 오디오를 표시하고, 텍스트나 마이크 입력을 전송하세요. 이 부분은 공식 SDK 퀵 스타트와 동일합니다. 애플리케이션별 작업은 아바타가 표시될 위치와 사용자가 대화를 시작, 중단, 종료하는 방식을 결정하는 것입니다.
지식 구성은 세션 생성 경로에 유지하세요. 이렇게 하면 백엔드에서 승인된 지식 베이스 ID를 다르게 선택함으로써 동일한 프론트엔드가 다양한 제품, 지역 또는 대상을 지원할 수 있습니다.
5단계: 근거 기반 답변 확인하기
아바타가 성공적으로 연결되었다고 해서 작업을 멈추지 마세요. 아바타가 의도한 지식을 실제로 사용하고 있는지, 답변을 사용할 수 없을 때 적절하게 대응하는지 확인하세요.
지식 베이스 관련 일반적인 문제 해결
아바타가 지식 베이스를 무시합니다. 올바른 knowledge_id 이(가) 세션 생성 요청에 포함되어 있는지 확인하세요. 지식 베이스가 대시보드에 존재하더라도 활성 스트리밍 아바타 세션에 연결되어 있지 않을 수 있습니다.
지식 베이스 콘텐츠를 찾을 수 없습니다. 테스트하기 전에 업로드된 모든 파일이나 공개 URL의 처리가 완료되었는지 확인하세요. 처리가 대기 중이거나 실패한 경우, 해당 콘텐츠는 아직 검색할 수 없습니다.
답변이 일관되지 않습니다. 오래되었거나 중복되거나 상충하는 소스 자료를 제거하세요. 각 사실에 대해 하나의 공식 버전만 유지하고, 명확한 제목을 사용하며, 답변이 소스에 명시적으로 나타나는 직접적인 질문으로 다시 테스트하세요.
세션은 작동하지만 대화가 작동하지 않습니다. 세션이 다음으로 생성되었는지 확인하세요: mode_type: 2. 그런 다음 SDK가 백엔드에서 반환된 동일한 세션에 연결되고 있는지, 그리고 아바타, 음성, 언어 및 세션 구성이 유효한지 확인하세요. 디버깅 중에 대체 세션을 생성하는 경우, 클라이언트가 이전 응답에서 만료된 자격 증명을 계속 사용하고 있지 않은지 확인하세요.
사용 사례
고객 지원. 방문자가 표준 고객 센터 검색보다 더 자연스러운 인터페이스를 통해 제품, 설정, 보증 또는 정책 관련 질문을 할 수 있도록 하세요.
제품 탐색. 승인된 영업 및 제품 콘텐츠를 사용하여 잠재 고객에게 기능, 플랜 및 권장 워크플로우를 안내하세요.
직원 교육. 온보딩 가이드와 내부 절차를 대화형 교육 어시스턴트로 전환하세요.
교육 및 이벤트. 학습자나 참석자에게 코스 자료, 발표자 노트 또는 이벤트 리소스에서 질문에 답변할 수 있는 실시간 발표자를 제공하세요.
출시 체크리스트
☐ 지식 소스가 최신 상태이며, 공식적이고, 완전히 처리되었습니다.
☐ 의도된 knowledge_id 이(가) 세션 생성 시 포함되었습니다.
☐ 정확한 질문, 의역된 질문, 범위를 벗어난 질문 및 후속 질문에 대한 테스트를 완료했습니다.
☐ 애플리케이션에서 세션 시작, 중단, 종료를 위한 명확한 제어 기능을 제공합니다.
☐ 최종 환경은 텍스트 및 마이크 입력 방식 모두로 테스트되었습니다.
리소스
자주 묻는 질문
무엇인가요? knowledge_id AKOOL 스트리밍 아바타에서 무엇인가요?
knowledge_id 은(는) AKOOL 지식 베이스의 식별자입니다. 스트리밍 아바타 세션에 이 ID를 추가하면, 아바타가 지식 기반 질문에 답변할 때 어떤 처리된 문서와 URL을 참조해야 하는지 AKOOL에 알려줍니다.
언제 knowledge_id 을(를) 스트리밍 아바타 세션에 추가해야 하나요?
브라우저가 세션에 참여하기 전, 백엔드에서 세션을 생성할 때 추가하세요. 이렇게 하면 처음부터 지식 베이스가 연결되며, 클라이언트 측 코드에 AKOOL API 키가 노출되는 것을 방지할 수 있습니다.
AKOOL 지식 베이스는 어떤 파일 형식을 사용할 수 있나요?
AKOOL 문서는 PDF, DOC, DOCX, TXT, MD, JSON, XML 및 CSV 파일을 지원합니다. 공개 URL을 추가할 수도 있습니다. 설명이 포함된 제목을 사용하여 깔끔하고 최신 상태인 소스를 사용하고, 검색 테스트를 수행하기 전에 처리가 완료될 때까지 기다려 주세요.
외부 LLM이나 RAG 지식 베이스를 직접 연결할 수 있나요?
문서화된 스트리밍 아바타 워크플로우는 AKOOL 지식 베이스를 사용합니다. 문서나 URL을 추가하고 해당 knowledge_id을(를) 획득한 다음, 세션을 생성할 때 이 ID를 포함하세요. 별도의 애플리케이션 수준 통합을 설계하고 검증하지 않는 한, 임의의 외부 벡터 데이터베이스나 RAG 서비스를 직접 연결할 수 있다고 가정해서는 안 됩니다.
