rw-integrate-documents

ドキュメントの連携（ナレッジベース）

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

使用元： +rw-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 のフロー全体については、+rw-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 を使用します。見出しがあると、アバターがナレッジを参照しやすくなります。
• 簡潔にまとめます。検索品質を高めるには、50,000 トークンの上限を十分に下回るようにしてください。
• トピックごとに整理します。大きなドキュメント 1 つより、トピックを絞った複数のドキュメントのほうが効果的です。
• 定期的に更新します。コンテンツが変わったらドキュメントを再作成し、ナレッジを最新の状態に保ってください。
• ドキュメントは Developer Portal の UI からも管理できます。