概述 - AgentKit 文档

知识库是智能体的外部知识来源，专门存放静态资料（产品文档、FAQ、文章等）。把它挂到智能体上，VeADK 会自动为智能体注入一个检索工具，让模型在需要资料时调用检索工具。是否检索由模型和指令决定；挂载知识库不保证每轮查询，也不能替代来源核实运行本页 local 示例前，安装 veadk-python[extensions] 并完成embedding 配置。包含 Agent 和 Runner 的示例还需完成模型配置

统一入口：`KnowledgeBase`

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

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

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

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

选择后端

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

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

绑定到智能体

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

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 时使用构造时设定的值。

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 对应的画像目录，使用自定义输出路径时应先将结果放入该默认目录

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 长期记忆中的用户画像加入查询提示。它要求同一智能体绑定可提供用户画像的长期记忆，与知识库画像文件并非同一数据来源

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

概述

统一入口：`KnowledgeBase`

通用参数

选择后端

绑定到智能体

直接检索

导入和权限边界

知识库画像

​统一入口：KnowledgeBase

​通用参数

​选择后端

​绑定到智能体

​直接检索

​导入和权限边界

​知识库画像

统一入口：`KnowledgeBase`

通用参数

选择后端

绑定到智能体

直接检索

导入和权限边界

知识库画像