integrate-documents

ドキュメントを統合する（ナレッジベース）

前提条件： 最初に +check-compatibility を実行してください。統合する前に、+fetch-api-reference を実行して最新の API リファレンスを読み込んでください。+setup-api-key — API 認証情報を設定する必要があります

使用元： +integrate-characters — ドキュメントはアバターにリンクされ、アバターに専門分野の知識を提供します

キャラクターが専門分野の知識を利用できるようにします。会話中にアバターが参照できるコンテンツをアップロードすると、正確で文脈に即した応答を返せるようになります。

ドキュメントを使用する場面

ユースケース	コンテンツの例
カスタマーサポート	FAQ、製品情報、会社のポリシー、返品手続き
クイズとゲーム	問題バンク、正解、採点ルール
教育	コース教材、参考資料、学習目標
ブランド体験	ブランドガイドライン、メッセージ、製品カタログ

制約

• 各アバターが利用できる知識は最大 50,000 トークンです
• 対応形式：プレーンテキストとMarkdown
• 今後のリリースでさらに多くの形式に対応する予定です

フロー

フローは次のとおりです：ドキュメントを作成する → アバターにリンクする

ステップ 1：ドキュメントを作成する

Node.js

import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const document = await client.documents.create({
  name: 'Product FAQ',
  content: `# Product FAQ

## What is your return policy?
We offer a 30-day return policy for all unused items in original packaging.

## How do I track my order?
Log in to your account and visit the Orders page. You'll find tracking information for all shipped orders.

## Do you offer international shipping?
Yes, we ship to over 50 countries. Shipping costs and delivery times vary by destination.`,
});

console.log('Document created:', document.id);

Python

from runwayml import RunwayML

client = RunwayML()

document = client.documents.create(
    name='Product FAQ',
    content="""# Product FAQ

## What is your return policy?
We offer a 30-day return policy for all unused items in original packaging.

## How do I track my order?
Log in to your account and visit the Orders page.

## Do you offer international shipping?
Yes, we ship to over 50 countries.""",
)

print('Document created:', document.id)

ステップ 2：ドキュメントをアバターにリンクする

ドキュメントを添付するには、アバターを更新します。既存のドキュメント添付ファイルはすべて置き換えられるため、リンクしたいドキュメント ID をすべて渡してください。

Node.js

await client.avatars.update(avatarId, {
  documentIds: [document.id],
});

Python

client.avatars.update(
    avatar_id,
    document_ids=[document.id],
)

複数のドキュメント

1 つのアバターに複数のドキュメントをリンクできます（合計は 50,000 トークン未満にする必要があります）。

const faq = await client.documents.create({
  name: 'FAQ',
  content: '...',
});

const policies = await client.documents.create({
  name: 'Company Policies',
  content: '...',
});

await client.avatars.update(avatarId, {
  documentIds: [faq.id, policies.id],
});

ステップ 3：セッションを開始する

ドキュメントをリンクすると、アバターは会話中に自動的にその知識を利用できるようになります。追加の設定は不要です。通常どおりセッションを開始してください。

const session = await client.realtimeSessions.create({
  model: 'gwm1_avatars',
  avatar: {
    type: 'custom',
    avatarId: avatarId,
  },
});

session = client.realtime_sessions.create(
    model='gwm1_avatars',
    avatar={
        'type': 'custom',
        'avatar_id': avatar_id,
    },
)

セッションの作成、ポーリング、WebRTC の全フローについては、+integrate-characters を参照してください。

統合パターン

ファイルからドキュメントを読み込む

ローカルファイルからコンテンツを読み込み、ドキュメントを作成します。

import fs from 'fs';
import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

// Read a local markdown file
const content = fs.readFileSync('./knowledge/product-faq.md', 'utf-8');

const document = await client.documents.create({
  name: 'Product FAQ',
  content,
});

from pathlib import Path
from runwayml import RunwayML

client = RunwayML()

content = Path('./knowledge/product-faq.md').read_text()

document = client.documents.create(
    name='Product FAQ',
    content=content,
)

動的な知識の更新

プログラムからドキュメントを更新します。CMS やデータベースとの同期に便利です。

// Example: API endpoint to update character knowledge
app.post('/api/avatar/update-knowledge', async (req, res) => {
  const { avatarId, documents } = req.body;

  // Create new documents
  const docIds = [];
  for (const doc of documents) {
    const created = await client.documents.create({
      name: doc.name,
      content: doc.content,
    });
    docIds.push(created.id);
  }

  // Link all documents to the avatar (replaces existing)
  await client.avatars.update(avatarId, {
    documentIds: docIds,
  });

  res.json({ success: true, documentCount: docIds.length });
});

ヒント

• Markdown を使用する：構造化されたコンテンツには Markdown を使います。見出しがあると、アバターが知識を参照しやすくなります。
• 簡潔にする：検索品質を高めるため、50,000 トークンの上限を十分に下回るようにしてください。
• トピックごとに整理する：大きなドキュメントを 1 つ作るよりも、トピックを絞った複数のドキュメントを作成するほうが効果的です。
• 定期的に更新する：コンテンツが変更されたらドキュメントを再作成し、知識を最新に保ってください。
• ドキュメントは Developer Portal の UI からも管理できます。