integrate-documents

集成文档（知识库）

前置条件： 请先运行 +check-compatibility。集成前运行 +fetch-api-reference，以加载最新的 API 参考。+setup-api-key — 必须配置 API 凭据

供以下功能使用： +integrate-characters — 文档会关联到 Avatar，为其提供特定领域的知识

让你的 Characters 获取特定领域的知识。上传内容，供你的 Avatar 在对话中参考，从而给出准确且符合上下文的回复。

何时使用文档

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

限制

• 每个 Avatar 最多支持 50,000 个 token 的知识
• 支持的格式：纯文本和 Markdown
• 计划在未来版本中支持更多格式

流程

流程如下：创建文档 → 将文档关联到 Avatar

步骤 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：将文档关联到 Avatar

更新你的 Avatar 以附加文档。这会替换所有现有的文档附件 — 请传入你希望关联的所有文档 ID。

Node.js

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

Python

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

多个文档

你可以将多个文档关联到同一个 avatar（总量必须低于 50,000 个 token）：

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：启动会话

关联文档后，Avatar 会在对话期间自动获取这些知识。像往常一样启动会话 — 无需额外配置：

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 来组织内容 — 标题有助于 Avatar 浏览知识。
• 保持简洁 — 为获得最佳检索质量，内容应远低于 50,000 个 token 的上限。
• 按主题组织 — 多篇主题明确的文档比一篇超长文档效果更好。
• 定期更新 — 内容变更时重新创建文档，以保持知识的时效性。
• 也可以通过 Developer Portal UI 管理文档。