integrate-documents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Integrate Documents (Knowledge Base)

集成文档（知识库）

PREREQUISITE: Run
+check-compatibility
first. Run
+fetch-api-reference
to load the latest API reference before integrating.
+setup-api-key
— API credentials must be configured
USED BY:
+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.

前置条件： 请先运行
+check-compatibility
。集成前运行
+fetch-api-reference
加载最新的API参考文档。
+setup-api-key
—— 必须先配置API凭据
适用场景：
+integrate-characters
—— 文档会关联到Avatars，为其赋予特定领域知识

让你的角色可访问特定领域知识。上传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（总token数必须低于50000）：

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

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

查看

+integrate-characters

了解完整的会话创建、轮询和WebRTC流程。

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

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

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

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

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更好地检索知识。
保持简洁 —— 内容尽量远低于50000 token上限，以获得最佳检索质量。
按主题组织 —— 多个聚焦特定主题的文档效果优于单个大而全的文档。
定期更新 —— 内容发生变化时重新创建文档，保证知识的时效性。
文档也可以通过开发者门户界面进行管理。