Agent在企业落地中，通常会使用各种开源的（LangChain、LlamaIndex、Haystack）或者平台性知识库产品（如Viking知识库）将各类普适知识聚合成知识库，在Agent应用中实现从知识到行为的闭环编排。火山引擎 AgentKit 原生支持导入 [Viking 知识库](https://www.volcengine.com/docs/84313/2117716?lang=zh)，本文为您介绍如何以最小成本快速、便捷的将 Viking 知识库（3 篇 AI 行业每周新闻）集成到 Agent 中使用，并完成 Viking 知识库全生命周期管理。 ## Viking 知识库介绍 Viking 知识库是火山引擎提供的一款检索增强生成（RAG）服务，能够智能解析分段结构化和非结构化文档，通过向量检索实现精准的语义匹配，结合大模型推理能力，为企业客户提供更准确、专业的问答效果，适用于客服应用、个人知识库、车机助手、论文伴读等多种场景。更多介绍请参见 [Viking知识库](https://www.volcengine.com/docs/84313/2117716?lang=zh)。 ## 前提条件 * 已开通 AgentKit 服务。若未开通，请登录 [AgentKit 控制台](https://console.volcengine.com/AgentKit)，根据系统引导开通产品。 * 已登录火山引擎控制台[获取 AK/SK](https://www.volcengine.com/docs/6291/65568)，进入 [API 访问密钥](https://console.volcengine.com/iam/keymanage/)页面，创建并获取 **Access Key ID ** 和 **Secret Access Key。** * 已基于 [VeADK](https://volcengine.github.io/veadk-python/cn/docs/framework/) 构建 Agent，并部署至 AgentKit 智能体运行时。 > 本实践基于 [AgentKit CLI](https://docs.volcengine.com/docs/86681/1844871) 预置模板 Basic Agent App（采用VeADK 框架）创建项目，并已将 Agent 部署至 AgentKit 智能体运行时。详情请参见[使用 AgentKit CLI 开发并部署智能体](https://docs.volcengine.com/docs/86681/1844871)。 * 您的本地已准备好 3 篇 AI 行业每周新闻（Word 格式）。 ## 将Viking知识库集成到AgentKit ### 步骤一：创建知识库 1. 登录[知识库控制台](https://console.volcengine.com/vikingdb/knowledge)。 2. 单击“创建知识库”按钮，根据需要选择知识库版本。您可以从知识库类型、计算和存储资源、计费等方面对比选择。本实践以“标准版”为例。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_8228f20989f5f74bdefb10bc7e7d4165.png) * 标准版：适用于个人开发者，500 个文档上传，共享计算资源配置，价格更实惠。 * 旗舰版：适用于企业/大规模团队，百万级文档处理，高额和灵活的计算资源，性能更优。 3. 单击“创建标准版知识库”按钮，配置以下信息。 |配置项 |说明 |示例 | |---|---|---| |库名称 |输入知识库名称，创建后，名称不支持修改。 |AgentKit_Knowledge_db | |知识内容 |选择知识库支持的内容类型。

* 图像/富文本：适用于文档，含图片、图表、架构图等复杂文档表现更优。

* 音视频：适用于含音视频文件，视频如培训视频、广告营销、比赛直播等，音频如会议录音、播客等。

* 结构化文档：主要包含成组的数据，如问答、用户数据等，通常为结构相对清晰和规范化的文档，无需平台分段。仅旗舰版知识库可用，如需使用，单击“返回”按钮，重新选择知识库类型。 |图像/富文本 | |Embedding 模型 |下拉选择知识库调用模型。

模型调用以实际模型用量和计价单位为准。详情请参见 [知识库计费](https://docs.volcengine.com/docs/84313/1414457)。 |Doubao\-embedding\-vision\-251215+关键词模型 | 4. 单击“创建库”按钮，完成操作。 ### 步骤二：上传文档并查看切片在知识库中导入文档并查看切片详情。切片用于将长文档按规则切成语义完整、长度适中的小片段，是 RAG（检索增强生成）系统里决定检索效果上限的核心步骤。 1. 单击“上传文档”按钮，选择“本地上传”。

说明

本实践以导入本地文件为例，您也可以按需选择其他导入方式。

2. 在**导入文档**页面，选择已准备好的 3 篇 AI 行业每周新闻（word格式）。

说明

选择文档处理策略和保存到目录本实践使用默认值，您也可以按需配置。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_db9e994f3062f0379d54321429cfad72.png) 3. 勾选“文档去重”按钮。开启后，系统将校验上传的文档内容和名称，若与已有的文档相同，则覆盖并更新原文档，以提高有效切片率及召回质量。 4. 单击“导入”按钮，等待导入成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_09fd15df220d717f87295aace6412abc.png) 5. 单击“切片详情”页签，可以查看每个文档的切片情况。鼠标悬浮至卡片，单击卡片右上角的“![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f7f09cac179692cb68b248389eaae683.png) ”图标，可以对切片内容进行修改。

说明

编辑切片会重新embedding切片，并产生费用。若更新文档，已编辑的切片内容将被更新的文档内容覆盖。

![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ab5415a9d0a4c2da0ee15cf214321d8e.png) ### 步骤三：知识检索与问答 #### 知识检索知识库创建完成、文档导入且处理完成后，即可进行在线检索，测试检索效果。 1. 单击“知识检索”页签，在左侧页面配置知识检索参数。 |**参数** |**作用** |**取值范围** | |---|---|---| |结果返回数量 |配置最终检索返回的结果数量。

* 如果没有打开重排模型，则表示检索返回重排后的 TopN 结果数量。

* 如果打开了重排模型，则表示模型排序后的结果的前 K 个文本片，K 为返回的结果数量。 |* 如果没有打开重排模型：[1, 1000]

* 如果打开了重排模型：[1, Top K] | |重排模型 |配置是否使用重排模型对检索到的文本片进行重新排序。

打开重排模型则会获得更准确的问题\-文本片相似性的评分，提升检索效果。

说明

打开后检索的时间会略有增长，且与召回文本数量成正比，建议合理设置召回文本数量。

|* Doubao\-Seed\-1.6\-rerank（默认）：Doubao\-Seed\-1.6\-Rerank 是字节自研的多模态重排序模型，面向文本、图片、视频等多模态内容检索召回得到的 Top\-K 候选进行更精细的语义匹配与相关性打分，输出更优的排序结果，可选阈值过滤与instruction设置。

* base\-multilingual\-rerank：速度快、长文本、支持70+种语言。

* m3\-v2\-rerank：常规文本、支持100+种语言。 | |进入重排数量 |开启“重排模型”后，需配置本参数。用于控制召回的文本片数量，即进入重排模型的文本片数量。

说明

建议召回数量稍大于结果返回数量，可提升检索效果。

|25 | |阈值过滤 |开启后，可设置最小相关性得分，低于对应分数的结果将不会被返回，默认 0.5。 |0.5 | |召回数量（Top K） |召回是指从海量的候选文本片中找出与问题最相关的 K 个文本片的过程。仅在打开了重排模型的时候可设置此项。建议设置召回数量略大于返回文本片数量，可提高生成准确性。 |[1, 200] | |更多参数\-Dense Weight |在创建知识库时，如果选择的向量化模型和索引算法支持混合检索，则检索时系统会同时考虑问题与候选文本片的语义相关性和字面上的匹配程度，获得更准确的检索结果。

Dense Weight 参数用于控制检索时语义相似程度的重要性权重，越偏向 1 表示越倾向于语义检索，越偏向 0 则表示越偏向于关键词匹配检索。 |[0.2, 1] | |API 调用 |保存设置后，您可以单击“API 调用”按钮获得 API 调用的请求体，便于您将调试好的设置嵌入您的应用当中。 |\-\- | 2. 在右侧页面，输入需要检索的内容。本实践为“Coding Agent”，返回结果如下。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4908c92416801ed348e0417fab36524b.png) #### 知识问答知识库创建完成、文档导入且处理完成后，即可进行知识问答，测试问题返回效果。 1. 单击“知识问答”页签，在左侧页面配置知识问答参数。 |**参数** |**作用** |**取值范围** | |---|---|---| |**检索参数** ||| |结果返回数量 |配置最终检索返回的结果数量。

* 如果没有若打开重排模型，则表示检索返回重排后的 TopN 结果数量。

* 如果打开了重排模型，则表示模型排序后的结果的前 K 个文本片，K 为返回的结果数量。 |* 如果没有打开重排模型：[1, 1000]

* 如果打开了重排模型：[1, Top K] | |问题改写 |启用后，将基于历史对话对本轮问题进行改写，使其具备更完整的语义信息，检索更准确。

说明

改写问题会增加检索时长和额外的 Tokens 消耗。

|默认关闭 | |重排模型 |配置是否使用重排模型对检索到的文本片进行重新排序。

打开重排模型则会获得更准确的问题\-文本片相似性的评分，提升检索效果。

说明

打开后检索的时间会略有增长，且与召回文本数量成正比，建议合理设置召回文本数量。

说明

建议召回数量稍大于结果返回数量，可提升检索效果。

说明

对于参考资料原文语序敏感的场景建议开启；对于切片内容逻辑独立的场景建议关闭。

|默认开启 | |**模型回答参数** ||| |选择模型 |配置知识库问答时使用的大模型，以及版本、推理接入点、思考深度等。 |\-\- | |拼接邻近文本片数量 |取该值作为召回重排后拼接邻近文本片的数量，若召回重排后文本片数为k，该值为p，则最终返回数量范围为[k，k+2*k*p] |[0, 5] | |文本片参数 |选择进入大模型的参数和顺序，选择后参数将按顺序拼接 Prompt 进入大模型。 | | |Prompt 配置 |当打开**使用大模型模型生成回答**时可设置。

* prompt 编排允许您设置传入大模型模型时如何组装用户问题和检索到的文本片，以及其他的回复要求。

* prompt 编排必须包含两个变量，使用方括号+变量名作为占位符。

* 在组织 prompt 时，您可以给大模型模型一些指示。以贴合您的使用场景。例如，让大模型模型使用检索到的文本作为背景信息回答问题，并在检索到的信息不能回答用户问题时转接人工客服，等等。

说明

平台也提供了几个核心场景的 Prompt 模板（客服场景、营销索联、思考阐述、模仿回复），您可以根据需要进行选择。

|\-\- | |引用开源 |开启后，回答末尾将展示引用的知识切片来源。 |\-\- | |图文混排 |开启后，若大模型的参考包含图片，则图片与文本同步显示在回复中。 |\-\- | |API 调用 |保存设置后，您可以单击“API 调用”按钮获得 API 调用的请求体，便于您将调试好的设置嵌入您的应用当中。 |\-\- | 2. 在右侧页面，输入需要检索的内容。本实践为“帮我搜索下近期 AI 新闻”，返回结果如下。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_e76862ff856c3ed4ae98eb0d0016d898.png) ### 步骤四：在 Agent 中集成知识库知识库准确完成并确认检索/问答均可用后，即可在 Agent 中集成知识库使用。 #### 1.导入知识库并获取知识库信息 1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中，选择“知识库”。 3. 单击“导入知识库”按钮。 4. 选择“Viking 知识库”。 5. 在弹出的对话框中，勾选需要导入的知识库。本实践为“AgentKit_Knowledge_db”。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_22557ceec70c4e5a864cd97553f44220.png) 6. 单击“导入”按钮，完成操作。 7. 单击刚导入的“AgentKit_Knowledge_db”名称，在“集成信息”页签下，获取环境变量配置信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9f699e250f9a9619604861b876a06235.png) #### 2.在 Agent 中集成知识库（VeADK）本文使用 [AgentKit CLI](https://docs.volcengine.com/docs/86681/1844871?lang=zh) 构建的 Agent 项目结构主要文件如下所示： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_8ee015db9e039dc2ba2a5904e64636df.png) * **.dockerignore**：用于记录构建 Docker 时需要忽略的文件或目录路径。Docker 构建时， `COPY . . `命令会忽略记录在本文件中的文件及目录，减小镜像体积并避免敏感信息泄露。 * **agentkit.yaml** ：AgentKit 项目的配置文件，定义了项目元信息、运行时环境变量、云部署参数等。 * **requirements.txt**：用于声明 Agent 所需的 Python 包依赖。Docker 构建时，将通过 `RUN uv pip install -r requirements.txt` 将其安装到容器镜像中。 * **simple_agent.py** ：Agent 应用入口文件，定义了 Agent 的行为包括接收用户请求、与模型对话、返回流式响应等。此时，只需对 Agent 进行以下修改： * 为 Agent 添加知识库`Knowledgebase`。 * 将获取的知识库环境变量添加到`agentkit.yaml`。 **修改步骤如下：** 1. **在本地环境设置环境变量** 1. （可选）若您退出了虚拟环境，请执行如下命令重新激活。否则，请跳过本步骤。 ```Bash source .venv/bin/activate ``` 2. 输入如下命令设置环境变量，添加 AK/SK 信息，其中``、``需替换为实际的 AK/SK 信息。

注意

由于 AK/SK 属于高敏感凭据，直接写入.env等静态配置文件存在泄露风险，在本地开发环境中配置火山引擎 AK/SK 时，推荐通过终端会话级环境变量导出的方式管理。

终端会话级环境变量为一次性配置，仅对当前终端窗口生效，关闭终端窗口后重新打开或开启新的终端窗口后，均需重新配置。

```Bash export VOLCENGINE_ACCESS_KEY= export VOLCENGINE_SECRET_KEY= ``` 1. 执行命令`cd `进入 Agent 项目根目录，``需替换为您的实际根目录路径。 2. **为`agentkit.yaml`文件添加上述步骤中获取到的知识库环境变量信息**。 1. 执行以下命令，打开 **AgentKit 项目配置文件。** ```Bash vim agentkit.yaml ``` 2. 按`i`键进入编辑模式，填写知识库环境变量信息。 ```Bash launch_types: cloud: runtime_envs: DATABASE_VIKING_COLLECTION: #请替换为您上述步骤中获取的知识库名称。本实践为“AgentKit_Knowledge_db” ``` 3. 按`esc`键退出编辑模式，然后输入`:wq`保存退出。 3. **在 Agent 中添加知识库相关配置。** 1. 执行以下命令，打开 **Agent 应用入口文件。** ```Bash vim simple_agent.py ``` 2. 按`i`键进入编辑模式，在代码中加入下方高亮部分内容。完整接入方式请参见[在 Agent 中集成知识库](https://docs.volcengine.com/docs/86681/1883770)。 ```Python # Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. import logging import os from veadk import Agent, Runner from agentkit.apps import AgentkitSimpleApp from veadk.prompts.agent_default_prompt import DEFAULT_DESCRIPTION, DEFAULT_INSTRUCTION from veadk.knowledgebase import KnowledgeBase logger = logging.getLogger(__name__) logger.setLevel(logging.INFO) app = AgentkitSimpleApp() agent_name = "Agent" description = DEFAULT_DESCRIPTION system_prompt = DEFAULT_INSTRUCTION tools = [] # from veadk.tools.builtin_tools.web_search import web_search # tools.append(web_search) #知识库 kb_collection_name = os.getenv("DATABASE_VIKING_COLLECTION") if not kb_collection_name: raise ValueError("DATABASE_VIKING_COLLECTION environment variable is not set") knowledgebase = KnowledgeBase(backend="viking", index=kb_collection_name) agent = Agent( name=agent_name, description=description, instruction=system_prompt, tools=tools, knowledgebase=knowledgebase, ) runner = Runner(agent=agent) @app.entrypoint async def run(payload: dict, headers: dict) -> str: prompt = payload["prompt"] user_id = headers["user_id"] session_id = headers["session_id"] logger.info( f"Running agent with prompt: {prompt}, user_id: {user_id}, session_id: {session_id}" ) response = await runner.run(messages=prompt, user_id=user_id, session_id=session_id) logger.info(f"Run response: {response}") return response @app.ping def ping() -> str: return "pong!" if __name__ == "__main__": app.run(host="0.0.0.0", port=8000) ``` ### 步骤五：部署至云上智能体运行时

说明

本文操作前提条件已明确基于 VeADK 构建了 Agent 并部署至 AgentKit 智能体运行时，因此在 Agent 代码中集成知识库后，可以直接执行agentkit launch命令。

1. 执行以下命令，将集成知识库的 Agent 应用构建并部署到 AgentKit 智能体运行时。 ```Python agentkit launch ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_46537dbfc0cd9dd3c1ef2fedd9258460.png) 2. [进入 AgentKit 智能体运行时](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/runtime?pageSize=10¤tPage=1)页面，单击目标智能体运行时名称，选择**版本管理**页签，查看已部署的智能体运行时发布记录及版本信息。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_2da0d20e99a772fe995051b0c6ca7e1e.png) 3. 您可以通过控制台“在线测试”或通过`invoke`命令验证 Agent 能否正常访问知识库。在线测试 1. 进入[智能体运行时](https://console.volcengine.com/agentkit/region:agentkit+cn-beijing/runtime?pageSize=10¤tPage=1)页面，单击目标智能体运行时操作列的“在线测试”按钮。 2. 在 **Body** **类型 ** 模块中，选择 **raw ** 并输入测试参数（本文调整 Prompt 为“你有哪些知识”），单击“调试”按钮发起 POST 请求。更多调试参数详情，请参见 [调用 Agent](https://www.volcengine.com/docs/86681/2122004)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1443468712b98281e43d8ade59346db6.png) 3. 在 **调试结果 ** 模块，确认状态码为 **200**，并验证返回内容符合预期。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_ed90e679738a5f68cb50ddde71222915.png) 使用 AgentKit CLI 命令 1. 在本地虚拟环境中执行如下命令，发送 Prompt。 ```Bash agentkit invoke "你有哪些知识" ``` 2. 根据回显信息，确认 Agent 可以正常回复。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b2bbad3d30455229c1ab32ba61efee96.png) ## 管理 Viking 知识库

说明

本实践仅为您介绍搭建 AgentKit 知识库后的相关管理操作，如需完整管理知识库的各项信息，请参见 Viking 知识库操作指南。

### 从 Agent 中移除知识库

注意

移除后立即生效，Agent 将无法再调用该知识库，请评估对业务的影响后谨慎操作。

从 Agent 中移除，只是解除知识库与 AgentKit 的关联关系，并不会实际删除原始知识库的资源。

1. 登录 [AgentKit 控制台](https://console.volcengine.com/agentkit)。 2. 在左侧导航树中，选择“知识库”。 3. 单击目标知识库操作列的“删除”按钮，完成操作。 ### 删除知识库

注意

本操作是在 Viking 知识库平台删除原始知识库资源，删除时会同步删除知识库所有数据（文档和资源）且无法恢复，请评估对业务的影响后谨慎操作。

在 Viking 知识库平台删除原始知识库资源后，Agent 将无法再调用该知识库。

1. 登录[知识库控制台](https://console.volcengine.com/vikingdb/knowledge)。 2. 单击目标知识库卡片的“... \> 删除”按钮，完成操作。