> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 概述

知识库是智能体的外部知识来源，专门存放静态资料（产品文档、FAQ、文章等）。把它挂到智能体上，VeADK 会自动为智能体注入一个检索工具，让模型在需要资料时调用检索工具。是否检索由模型和指令决定；挂载知识库不保证每轮查询，也不能替代来源核实

运行本页 local 示例前，安装 `veadk-python[extensions]` 并完成[embedding 配置](/productions/veadk/preview/zh/components/knowledge/local#环境变量配置)。包含 Agent 和 Runner 的示例还需完成[模型配置](/productions/veadk/preview/zh/components/agent/model)

## 统一入口：`KnowledgeBase`

无论使用哪种后端，均通过统一的 `veadk.knowledgebase.KnowledgeBase` 接入。它根据 `backend` 选择存储后端，并提供一致的知识注入与检索接口。知识注入支持三种来源：

* 从文件导入：`kb.add_from_files([...])`；
* 从目录导入：`kb.add_from_directory("./docs")`；
* 从文本导入：`kb.add_from_text([...])`。

```python lines theme={null}
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="local", index="company_faq")

kb.add_from_text(
    [
        "公司的标准年假为每年 15 天，入职满一年起享受。",
        "经主管批准后，员工每周最多可远程办公 2 天。",
    ]
)
```

### 通用参数

`KnowledgeBase` 的字段对所有后端通用：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `backend` | `"local" \| "opensearch" \| "redis" \| "milvus" \| "tos_vector" \| "viking" \| "context_search" \| "openviking"` | `"local"` | 选择后端 |
| `backend_config` | `dict` | `{}` | 后端专用配置。非空时必须在配置中提供 `index` |
| `top_k` | `int` | `10` | 检索时返回最相似的片段数量。`search` 方法可临时覆盖 |
| `app_name` | `str` | `""` | 应用名。当 `index` 为空时作为其回退值 |
| `index` | `str` | `""` | 知识库索引/集合名。为空时回退到 `app_name`；两者皆空则初始化失败 |
| `name` | `str` | `user_knowledgebase` | 知识库名称，用于向智能体描述该知识库 |
| `description` | `str` | `This knowledgebase stores some user-related information.` | 知识库描述，用于向智能体说明其用途 |
| `enable_profile` | `bool` | `False` | 是否启用知识库画像能力 |
| `query_with_user_profile` | `bool` | `False` | 是否在检索时结合用户画像。需在智能体上绑定支持画像的 Viking 长期记忆，不要求知识库本身使用 Viking |

<Note>
  向量类后端（`local`、`opensearch`、`redis`、`milvus`、`tos_vector`）会对知识文本做向量化，需要安装扩展依赖并配置 embedding 模型。`viking`、`context_search` 与 `openviking` 在服务端处理资源，无需本地 embedding。
</Note>

## 选择后端

调试可用 `local`；使用托管检索服务时可选择 `viking`、`context_search` 或 `openviking`；已有向量存储时可选择 `opensearch`、`redis`、`milvus` 或 `tos_vector`

| 后端 | 存储 | 依赖 | 适用场景 | 文档 |
| :- | :- | :- | :- | :- |
| `local` | 内存向量索引 | `extensions` + embedding | 本地调试（进程退出后数据丢失） | [本地内存](/productions/veadk/preview/zh/components/knowledge/local) |
| `opensearch` | OpenSearch 向量库 | OpenSearch + `extensions` + embedding | 自建向量检索 | [OpenSearch](/productions/veadk/preview/zh/components/knowledge/opensearch) |
| `redis` | Redis 向量库 | Redis(RediSearch) + `extensions` + embedding | 低延迟自建向量检索 | [Redis](/productions/veadk/preview/zh/components/knowledge/redis) |
| `milvus` | Milvus collection | Milvus + `extensions` + embedding | 自建或托管 Milvus | [Milvus](/productions/veadk/preview/zh/components/knowledge/milvus) |
| `tos_vector` | TOS 向量桶 | 火山引擎账号 + `extensions` + embedding | 火山引擎对象存储向量库 | [TOS 向量库](/productions/veadk/preview/zh/components/knowledge/tos-vector) |
| `viking` | VikingDB 知识库（托管） | 火山引擎账号 | 生产推荐 | [VikingDB](/productions/veadk/preview/zh/components/knowledge/viking) |
| `context_search` | Context Search（托管） | 火山引擎账号 | 生产推荐 | [Context Search](/productions/veadk/preview/zh/components/knowledge/context-search) |
| `openviking` | OpenViking 资源目录 | OpenViking 服务 | 服务端资源解析与检索 | [OpenViking](/productions/veadk/preview/zh/components/knowledge/openviking) |

## 绑定到智能体

把 `knowledgebase` 传给 `Agent` 后，智能体会**自动获得 `load_knowledgebase` 工具**，在回答问题时自主决定是否检索知识库。

```python lines theme={null}
import asyncio

from veadk import Agent, Runner
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="local", index="company_faq")
kb.add_from_text("公司的标准年假为每年 15 天，入职满一年起享受。")

agent = Agent(
    name="kb_agent",
    instruction="你是一个知识渊博的助手，请优先利用知识库回答问题。",
    knowledgebase=kb,
)

runner = Runner(agent=agent, app_name="company_faq")
print(asyncio.run(runner.run(messages="年假有多少天？")))
```

## 直接检索

除了智能体运行时自动检索，也可以直接调用 `search` 做语义搜索，用于调试或自定义 RAG。`top_k` 为 0 时使用构造时设定的值。

```python lines theme={null}
entries = kb.search(query="年假", top_k=3)
for entry in entries:
    print(entry.content)
```

## 导入和权限边界

导入方法返回布尔值；托管后端返回成功可能只表示资料已提交，还需等待服务端解析完成。`search()` 返回 `KnowledgebaseEntry` 列表，文本位于 `entry.content`；无命中时列表为空。重复导入不保证去重，生产导入应记录已处理资料

知识库通常在应用范围共享，不会自动按会话 user\_id 过滤权限。先确定每个知识库允许访问的资料，再将它挂载到智能体。各后端的目录递归行为、媒体提取与过滤参数不同，不能把某一后端选项用于所有后端。停止使用后可调用 `kb.close()` 释放后端连接

## 知识库画像

`enable_profile` 会让智能体先参考知识库画像，再生成检索词，默认关闭。启用前使用 `await kb.generate_profiles(files=[...])` 生成画像，并保留默认目录中的结果文件；该操作不会替代知识导入

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `files` | `list[str]` | 必填 | 已存在、可作为文本读取的文件路径；PDF 等二进制资料需先转换为文本 |
| `profile_path` | `str` | `""` | 自定义输出目录；空值使用 `./profiles/knowledgebase/profiles_{index}` |

当前画像生成使用 `deepseek-v3-2-251201`，运行前确认配置的模型服务可访问该模型；仅修改主智能体模型不会替换画像生成模型。BytePlus 等环境未提供此模型时保持画像功能关闭，普通知识检索仍可使用

以下示例先准备文本、导入知识并生成画像，检查输出非空后启用功能。方法生成文件，不返回画像列表；检索默认读取当前工作目录下与 `index` 对应的画像目录，使用自定义输出路径时应先将结果放入该默认目录

```python lines theme={null}
import asyncio
import json
from pathlib import Path
from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

async def main():
    source = Path("company_faq.txt")
    source.write_text("Employees receive 15 days of annual leave after one year of service", encoding="utf-8")
    kb = KnowledgeBase(backend="local", index="company_faq")
    try:
        assert kb.add_from_files([str(source)])
        await kb.generate_profiles(files=[str(source)])
        profile_list = Path("profiles/knowledgebase/profiles_company_faq/profile_list.json")
        names = json.loads(profile_list.read_text(encoding="utf-8"))
        if not names:
            raise RuntimeError("No profiles were generated")
        print(names)
        kb.enable_profile = True
        agent = Agent(name="faq_agent", knowledgebase=kb)
        print(agent.name)
    finally:
        kb.close()

asyncio.run(main())
```

`query_with_user_profile` 是另一项独立配置，用于把 Viking 长期记忆中的用户画像加入查询提示。它要求同一智能体绑定可提供用户画像的长期记忆，与知识库画像文件并非同一数据来源