> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 管理文档

通过[知识库控制面板](https://elevenlabs.io/app/agents/knowledge-base)、CLI 或 API 管理知识库。了解知识库是什么以及智能体如何使用它，请参阅[知识库](/docs/zh/eleven-agents/customization/knowledge-base)。

![知识库主界面，显示文档
列表](/docs/_fern-img/0887213c4d8099240b7e5a8fec86fc75f4763e8fd80a6f7a6de33545c45f37a2.webp)

## 添加文档

可通过文件、网页或纯文本创建文档。创建后，将文档关联到智能体，即可在对话中使用其内容。

#### 控制面板

在[知识库控制面板](https://elevenlabs.io/app/agents/knowledge-base)或智能体配置页面中，点击 **添加文档**，然后选择来源。

#### 文件

上传 PDF、TXT、DOCX、HTML、EPUB 或 Markdown 格式的文档，每个文件最大 20MB。

![文件上传界面，显示支持的格式和 20MB 大小限制](/docs/_fern-img/b428874877d6aa2b24167c0293709e6a52a096a13b02244c0a5463139d3988e4.webp)

#### URL

粘贴 URL 即可导入网页。如需采集整个网站，请使用抓取选项——可从起始 URL 沿链接抓取整个网站，也可从网站的站点地图导入页面。如果页面导入失败，请确认网站允许[爬虫用户代理](#crawler-user-agent)。

![URL 导入界面，用户可粘贴文档链接](/docs/_fern-img/8523ea5c5ae0418007eb7042d4af3e792a111ca41b74a090357df34cd5b4a369.webp)

> **Warning**
>
> 请确保你有权使用所提供 URL 中的内容。

#### 文本

手动输入文本并命名。

![文本输入界面，用户可命名并添加自定义内容](/docs/_fern-img/4e44e310335dcea24b4832d38813992f1bdc55ef85b4e54353963dc47e9baa0a.webp)

#### CLI

CLI 不直接上传知识库文档。请通过控制面板或 API 创建文档，然后将返回的文档 ID 关联到智能体配置。

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

设置 `conversation_config.agent.prompt.knowledge_base`：

```json
{
  "conversation_config": {
    "agent": {
      "prompt": {
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "i2YYI6huwBmcgYydAXARmQJc3pmX",
            "usage_mode": "auto"
          }
        ]
      }
    }
  }
}
```

#### 推送更改

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### API

创建每个文档，然后将返回的 ID 关联到智能体配置。

```python
import os

from dotenv import load_dotenv
from elevenlabs import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

# Create a document from text
text_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_text(
    text="The airspeed velocity of an unladen swallow (European) is 24 miles per hour, or roughly 11 meters per second.",
    name="Unladen Swallow facts",
)

# Create a document from a URL
url_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_url(
    url="https://en.wikipedia.org/wiki/Unladen_swallow",
    name="Unladen Swallow Wikipedia page",
)

# Create a document from a file
file_doc = elevenlabs.conversational_ai.knowledge_base.documents.create_from_file(
    file=open("/path/to/unladen-swallow-facts.txt", "rb"),
    name="Unladen Swallow Facts",
)

# Attach the documents to an agent
elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "prompt": {
                "knowledge_base": [
                    {"type": "text", "name": text_doc.name, "id": text_doc.id},
                    {"type": "url", "name": url_doc.name, "id": url_doc.id},
                    {"type": "file", "name": file_doc.name, "id": file_doc.id},
                ]
            }
        }
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import fs from "node:fs";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

// Create a document from text
const textDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromText({
  name: "Unladen Swallow Facts",
  text: "The airspeed velocity of an unladen swallow (European) is 24 miles per hour, or roughly 11 meters per second.",
});

// Create a document from a URL
const urlDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromUrl({
  name: "Unladen Swallow Wikipedia page",
  url: "https://en.wikipedia.org/wiki/Unladen_swallow",
});

// Create a document from a file
const fileBuffer = fs.readFileSync("/path/to/unladen-swallow-facts.txt");
const file = new File([fileBuffer], "unladen-swallow-facts.txt", { type: "text/plain" });
const fileDoc = await elevenlabs.conversationalAi.knowledgeBase.documents.createFromFile({
  name: "Unladen Swallow Facts",
  file,
});

// Attach the documents to an agent
await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      prompt: {
        knowledgeBase: [
          { type: "text", name: textDoc.name, id: textDoc.id },
          { type: "url", name: urlDoc.name, id: urlDoc.id },
          { type: "file", name: fileDoc.name, id: fileDoc.id },
        ],
      },
    },
  },
});
```

如需将整个网站抓取到文档文件夹中，而非添加单个页面，请启动抓取任务。抓取为异步执行——可使用返回的任务 ID 查看状态或取消任务。

```python
crawl = elevenlabs.conversational_ai.knowledge_base.crawl_jobs.create(
    url="https://elevenlabs.io/docs",
    max_depth=3,
    max_pages=1000,
)
```

```typescript
const crawl = await elevenlabs.conversationalAi.knowledgeBase.crawlJobs.create({
  url: "https://elevenlabs.io/docs",
  maxDepth: 3,
  maxPages: 1000,
});
```

### 爬虫用户代理

URL 导入和抓取任务使用用户代理 `ElevenlabsBot/1.0` 获取页面。

> **Warning**
>
> 如果网站位于 CDN、WAF 或机器人防护规则之后，请允许此用户代理，以便爬虫读取页面。请求被拦截时，仍会创建文档，但无法从中提取内容。

爬虫还会遵循 `robots.txt`。禁止 `ElevenlabsBot` 或所有用户代理访问的页面会被跳过；如果预期应被索引的页面缺失，请检查相关规则。要明确允许爬虫访问：

**`robots.txt`**

```txt robots.txt
User-agent: ElevenlabsBot
Allow: /
```

## 将现有文档添加到智能体

文档可在多个智能体之间复用，因此共享知识只需维护一次。

1. 前往智能体[配置](https://elevenlabs.io/app/agents/agents)。
2. 找到知识库部分，然后点击 **添加文档**。
3. 从知识库中选择现有文档，或上传新文档。

![将文档添加到
智能体的界面](/docs/_fern-img/8e8a6a2df244ed20d1ab889c8ae5dda76aefed0d15f3dd2fe09c35b281c63673.webp)

> **Tip**
>
> 在多个智能体之间复用文档可保持知识一致，避免重复上传。

## 编辑文档

可直接编辑文档内容，无需删除后重新上传。编辑文档会自动重新生成内容搜索分块和 RAG 嵌入向量，确保搜索和智能体检索保持同步。

* **文本和文件文档**：直接编辑内容并保存。
* **文件文档**：也可使用新版本替换原文件。
* **URL 文档**：自动同步关闭时可编辑内容。自动同步开启时，同步周期会管理文档，无法手动编辑。

![在知识库中直接编辑文档
内容](/docs/_fern-img/4ea01bb2c13162f31f7610b049ae0db542e279a26da38f4c79f17fb89a8524f5.webp)

```python
# Update a document's name or content
elevenlabs.conversational_ai.knowledge_base.documents.update(
    documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
    name="Unladen Swallow Facts",
    content="The airspeed velocity of an unladen swallow (European) is 24 miles per hour.",
)

# Replace the underlying file of a file document

elevenlabs.conversational_ai.knowledge_base.document.update_file(
documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
file=open("/path/to/unladen-swallow-facts-v2.txt", "rb"),
)

```

```typescript
// Update a document's name or content
await elevenlabs.conversationalAi.knowledgeBase.documents.update("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  name: "Unladen Swallow Facts",
  content: "The airspeed velocity of an unladen swallow (European) is 24 miles per hour.",
});

// Replace the underlying file of a file document
const fileBuffer = fs.readFileSync("/path/to/unladen-swallow-facts-v2.txt");
const updatedFile = new File([fileBuffer], "unladen-swallow-facts-v2.txt", { type: "text/plain" });
await elevenlabs.conversationalAi.knowledgeBase.document.updateFile("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  file: updatedFile,
});
```

## 保持 URL 内容最新

通过 URL 创建的文档可刷新，以重新获取来源中的最新内容。刷新会重新索引文档，使启用 RAG 的智能体使用更新后的内容。

```python
elevenlabs.conversational_ai.knowledge_base.document.refresh(
    documentation_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
)
```

```typescript
await elevenlabs.conversationalAi.knowledgeBase.document.refresh("i2YYI6huwBmcgYydAXARmQJc3pmX");
```

在控制面板中，还可启用自动同步，按计划自动刷新 URL 文档，使内容无需手动更新也能保持最新。

## 使用文件夹整理

文件夹可将相关文档分组，便于管理和批量关联。创建文件夹后，可通过控制面板或 API 将文档移入其中。

关联到智能体的文件夹会通过 RAG 提供其中所有文档，因此智能体必须启用 RAG 才能使用文件夹。

![创建文件夹并将文档移入
其中](/docs/_fern-img/8267c0d4a36282c1fcaaacf0a665e5caf8c4cf6f2908451fc5a3b1cf6a8dd2e0.webp)

```python
# Create a folder
folder = elevenlabs.conversational_ai.knowledge_base.documents.create_folder(
    name="Product documentation",
)

# Move a document into the folder

elevenlabs.conversational_ai.knowledge_base.documents.move(
document_id="i2YYI6huwBmcgYydAXARmQJc3pmX",
move_to=folder.id,
)

```

```typescript
// Create a folder
const folder = await elevenlabs.conversationalAi.knowledgeBase.documents.createFolder({
  name: "Product documentation",
});

// Move a document into the folder
await elevenlabs.conversationalAi.knowledgeBase.documents.move("i2YYI6huwBmcgYydAXARmQJc3pmX", {
  moveTo: folder.id,
});
```

## 依赖关系和删除

每个文档都有一个 **依赖智能体** 标签页，其中列出了当前依赖该文档的智能体。

![文档详情视图，显示“依赖智能体”
标签页](/docs/_fern-img/20ecce9f1db77d27bdf760b4a90c9bd2baacb612b48cf660e0f395c82aa3a725.webp)

只要有智能体依赖某个文档，就无法删除该文档。请先从这些智能体中移除文档，或使用强制删除一次性将其从所有依赖项中解除关联。