rw-integrate-documents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrate Documents (Knowledge Base)

集成文档（知识库）

PREREQUISITE: Run
+rw-check-compatibility
first. Run
+rw-fetch-api-reference
to load the latest API reference before integrating.
+rw-setup-api-key
— API credentials must be configured
USED BY:
+rw-integrate-characters
— Documents are linked to Avatars to give them domain-specific knowledge

Give your Characters access to domain-specific knowledge. Upload content that your Avatar can reference during conversations for accurate, contextual responses.

前置要求： 先运行
+rw-check-compatibility
。在集成前运行
+rw-fetch-api-reference
加载最新的API参考文档。
+rw-setup-api-key
— 必须配置API凭证
关联命令：
+rw-integrate-characters
— 文档与Avatar关联，为其赋予特定领域的知识

为你的Characters赋予特定领域的知识权限。上传Avatar可在对话中参考的内容，使其给出准确且贴合上下文的回复。

When to Use Documents

文档适用场景

Use Case	Example Content
Customer support	FAQs, product info, company policies, return procedures
Quizzes & games	Question banks, correct answers, scoring rules
Education	Course material, reference content, learning objectives
Brand experiences	Brand guidelines, messaging, product catalogs

使用场景	示例内容
客户支持	常见问题、产品信息、公司政策、退货流程
测验与游戏	题库、正确答案、评分规则
教育领域	课程资料、参考内容、学习目标
品牌体验	品牌指南、宣传话术、产品目录

Constraints

限制条件

Each Avatar supports up to 50,000 tokens of knowledge
Supported formats: plain text and Markdown
More formats planned for future releases

每个Avatar最多支持50,000 tokens的知识容量
支持格式：纯文本和Markdown
未来版本计划支持更多格式

Flow

操作流程

The flow is: Create a Document → Link it to an Avatar

流程为：创建文档 → 关联至Avatar

Step 1: Create a Document

步骤1：创建文档

Node.js

javascript

import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

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

javascript

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?

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);

undefined

Yes, we ship to over 50 countries. Shipping costs and delivery times vary by destination.`, });

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

undefined

Python

python

from runwayml import RunwayML

client = RunwayML()

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

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?

Do you offer international shipping?

Yes, we ship to over 50 countries.""", )

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

undefined

Yes, we ship to over 50 countries.""", )

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

undefined

Step 2: Link the Document to an Avatar

步骤2：将文档关联至Avatar

Update your Avatar to attach the document. This replaces any existing document attachments — pass all document IDs you want linked.

更新你的Avatar以附加文档。此操作会替换所有现有文档附件 — 传入所有想要关联的文档ID。

Node.js

javascript

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

javascript

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

Python

python

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

python

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

Multiple Documents

关联多个文档

You can link multiple documents to a single avatar (total must stay under 50,000 tokens):

javascript

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],
});

你可以将多个文档关联至单个Avatar（总容量需保持在50,000 tokens以内）：

javascript

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],
});

Step 3: Start a Session

步骤3：启动会话

Once documents are linked, the Avatar automatically has access to the knowledge during conversations. Start a session as usual — no additional configuration needed:

javascript

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

python

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

See

+rw-integrate-characters

for the full session creation, polling, and WebRTC flow.

文档关联完成后，Avatar会在对话中自动获取知识库内容。按常规方式启动会话即可 — 无需额外配置：

javascript

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

python

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

完整的会话创建、轮询及WebRTC流程请查看

+rw-integrate-characters

。

Integration Patterns

集成模式

Load Documents from Files

从文件加载文档

Read content from local files and create documents:

javascript

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,
});

python

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,
)

读取本地文件内容并创建文档：

javascript

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

const client = new RunwayML();

// 读取本地Markdown文件
const content = fs.readFileSync('./knowledge/product-faq.md', 'utf-8');

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

python

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,
)

Dynamic Knowledge Updates

动态更新知识

Update documents programmatically — useful for syncing with a CMS or database:

javascript

// 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 });
});

通过编程方式更新文档 — 适用于与CMS或数据库同步的场景：

javascript

// 示例：更新角色知识的API端点
app.post('/api/avatar/update-knowledge', async (req, res) => {
  const { avatarId, documents } = req.body;

  // 创建新文档
  const docIds = [];
  for (const doc of documents) {
    const created = await client.documents.create({
      name: doc.name,
      content: doc.content,
    });
    docIds.push(created.id);
  }

  // 将所有文档关联至Avatar（替换现有关联）
  await client.avatars.update(avatarId, {
    documentIds: docIds,
  });

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

Tips

小贴士

Use Markdown for structured content — headings help the Avatar navigate the knowledge.
Be concise — stay well under the 50,000 token limit for best retrieval quality.
Organize by topic — multiple focused documents work better than one giant document.
Update regularly — keep knowledge current by re-creating documents when content changes.
Documents can also be managed via the Developer Portal UI.

使用Markdown编写结构化内容 — 标题有助于Avatar快速定位知识内容。
内容简洁 — 保持远低于50,000 token的限制，以获得最佳的检索质量。
按主题分类 — 多个聚焦主题的文档效果优于单个巨型文档。
定期更新 — 内容变更时重新创建文档，保持知识的时效性。
也可通过开发者门户UI管理文档。