Nexent 搜索工具(Search Tools)全解析:本地知识库、AIDP 多模态检索与公共网络搜索的配置与实战指南

原创2026-10-11 22:10:151,930 阅读
文章标签:AI AgentAI 应用后端前端大模型RAG

Nexent 搜索工具(Search Tools)全解析:本地知识库、AIDP 多模态检索与公共网络搜索的配置与实战指南

导读

Nexent 的 Search Tools 是一组内置检索类 Agent 工具,覆盖本地/私有知识库检索(knowledge_base_search、aidp_search、datamate_search、dify_search)与公共网络搜索(exa_search、tavily_search、linkup_search)两大方向,可满足实时资讯获取、行业资料查询、私有文档问答以及多模态企业知识库召回等场景。本文以官方文档 search-tools.md 为主体骨架,结合仓库中 sdk/nexent/core/tools/ 与 sdk/nexent/core/ext_components/aidp/aidp_search_tool.py 的源码实现,逐一拆解每个工具的配置参数、搜索参数、默认值与底层行为,并给出完整的上手步骤与安全实践,读完即可在 Nexent 平台中正确配置并验证这些检索工具。

一、工具全景:两大类、七个内置搜索工具

Nexent 通过 smolagents 的 Tool 基类实现这些检索能力,全部以 *_search 命名并纳入内置工具生命周期管理。从 backend/consts/tool_labels.py 的内置标签定义可以看到,平台按用途对它们做了两类归类:

  • _category_search(标签 search):tavily_search、exa_search、linkup_search、search_memory、knowledge_base_search
  • _category_kb(标签 knowledge-base):dify_search、datamate_search、idata_search、haotian_search、ragflow_search、aidp_search

这些标签在租户首次初始化工具表时(update_tool_table_from_scan_tool_list())写入,用于前端能力分组与 Agent 能力画像识别。

按数据源性质,七个核心搜索工具可划分如下:

分类 工具名 数据源 典型场景
本地知识库 knowledge_base_search Nexent 本地 KB(多检索模式) 私有文档、内部规范、技术资料问答
企业知识库 aidp_search AIDP 企业 KB(FusionSearch 多模态) 检索文档、表格、图片、技术图纸
第三方知识库 datamate_search DataMate KB 数据平台内领域资料检索
第三方知识库 dify_search Dify KB 已有 Dify 知识库资产复用
公共网络 exa_search Exa 实时新闻、开放网络证据
公共网络 tavily_search Tavily 实时网络检索(含图片)
公共网络 linkup_search Linkup 文本/图片混合检索

典型使用场景包括:

  • 检索内部文档、规范与行业参考资料(本地 KB、DataMate、Dify);
  • 查询企业 AIDP 知识库中的文档、表格、图片或技术图纸(aidp_search 多模态输出);
  • 获取最新新闻或网络证据(Exa / Tavily / Linkup);
  • 在返回文本的同时附带图片引用(可选过滤)。

二、本地知识库检索:knowledge_base_search

knowledge_base_search 是面向 Nexent 本地知识库的通用检索工具,支持多种检索模式,适合领域知识、技术文档、个人笔记等私有资料的问答。

配置参数

参数 说明 默认值
top_k 返回结果数量上限 3

从 knowledge_base_search_tool.py 的构造函数可见,top_k 通过 Pydantic Field 声明为 default=3, ge=1, le=100,即取值范围限制在 1~100。工具还声明了 index_names(要检索的知识库索引名列表)作为初始化参数。

搜索参数

  • query(必填):搜索查询词。
  • search_mode:检索模式,可选 hybrid(默认)、accurate、semantic。源码中的 init_param_descriptions 明确写出 "The search mode, optional values: hybrid, accurate, semantic",即混合检索 / 精确检索 / 语义检索三种模式。
  • index_names(可选):知识库名称列表,可使用用户可见名称或内部索引名。

返回结果与依赖约束

返回结果包含标题、路径/URL、来源类型、分数与引用信息;若未选择任何知识库,工具会给出明确警告。

值得注意的是,该工具依赖向量库与 Embedding 模型。在 backend/services/tool_configuration_service.py 的实例化逻辑中:

  • 若未提供 index_names 或 tenant_id,会抛出 "Embedding model is required for knowledge_base_search but index_names or tenant_id is missing";
  • 通过 get_embedding_model_by_index_name() 按首个索引名解析 Embedding 模型,找不到则报错提示"请为该知识库配置 Embedding 模型";
  • 支持可选的 rerank / rerank_model_name 配置,启用后通过 get_rerank_model() 加载重排序模型;
  • 工具内部维护 display_name_to_index_map(KB 显示名到索引名的映射),供 LLM 以用户可读名称传参时自动换算;
  • 还支持 document_paths 内部访问控制参数,可将检索结果限定到指定文档路径。

三、企业知识库检索:aidp_search(AIDP FusionSearch 多模态)

aidp_search 通过 AIDP 平台的 FusionSearch 接口对企业知识库进行多模态检索,支持混合/向量/全文三种检索方法,并可选启用重排序、查询改写与关联 Chunk 检索。实现位于 aidp_search_tool.py。

配置参数

参数 说明 默认值
server_url AIDP API 基础地址,例如 https://141.111.61.70:30080 必填
api_key AIDP API 密钥,通常以 ak_ 开头,由 AIDP 平台管理员签发 必填
tenant_id AIDP API 路径中使用的租户标识,例如 aidp 必填
kds_list JSON 字符串数组,列出要检索的知识库 ID(kds_id),如 ["aidp-kb-01", "aidp-kb-02"],决定工具默认访问哪些 AIDP KB 必填
search_method 检索方法:hybrid_search(默认,融合检索)/ vector_search(向量检索)/ full_text_search(全文检索) hybrid_search
reranking_enable 是否启用重排序 True
reranking_mode 重排序模式:performance(默认)/ high_accuracy performance
rewrite_enable 是否启用查询改写 False
related_search_enable 是否启用关联 Chunk 检索 False
score_threshold 相似度阈值(0~1) 0.0
top_k 返回结果数量(1~100) 10
multi_modal 是否返回多模态块(图片/表格) True

源码构造函数(aidp_search_tool.py)与文档参数一一对应,并对 kds_list 做了严格校验(_parse_kds_list):必须是合法 JSON 数组、长度 0~10,否则抛错。score_threshold 限幅 0.0~1.0,top_k 限幅 1~100。

搜索参数

  • query(必填):搜索查询词。
  • kds_list(可选):本次搜索的知识库 ID 列表;缺省时回退到配置中的 kds_list。

双通道输出与权限过滤

aidp_search 通过双通道返回检索结果:所有块(文本、表格、图片)作为 SEARCH_CONTENT 输出,同时图片块的 file_url 还会作为 PICTURE_WEB 单独投递。图片块使用安全的 Markdown 图片标记(/__aidp_image__/ 路径),Agent 在引用时应原样复制该标记,不得自行编造或暴露图片 URL(参见 aidp_search_tool.py 的 description 约束)。

权限方面有两个重要行为:

  1. 检索范围受当前聊天用户的 AIDP 权限白名单过滤:无论使用默认 kds_list 还是 LLM 提供的 kds_list,都会与用户可访问的 KB 集合取交集,未授权 KB 被静默丢弃;
  2. 过滤后若无任何可访问 KB,工具返回明确的"无权限"提示信息,而非静默返回空结果。

从服务端实现看,AIDP 凭据(AIDP_SERVER_URL、AIDP_API_KEY、AIDP_TENANT_ID)来自进程环境变量而非客户端提交,见 tool_configuration_service.py 的校验逻辑——测试连接时若环境未配置会提示 "AIDP is not configured for this deployment"。底层检索走 GET/POST /KnowledgeBase/Tenants/{tenant_id}/Retrieval/FusionSearch 接口,fusion_search_impl()(aidp_service.py)构造与 SDK 相同的请求体:kds_list、search_method、reranking_enable、rewrite_enable、related_search_enable、score_threshold、top_k、multi_modal,返回 {title, text, score, file_url, chunk_type, ...} 记录。

四、第三方知识库检索:datamate_search 与 dify_search

这两个工具用于对接平台之外的第三方知识库,将已有数据资产接入 Nexent Agent 检索链路。

datamate_search:DataMate 知识库检索

配置参数:

参数 说明 默认值
server_url DataMate 服务器地址,如 http://192.168.1.100:8080 或 https://datamate.example.com:8443 必填
verify_ssl 是否校验 SSL 证书(HTTPS 默认 False,HTTP 默认 True) 视协议而定
top_k 返回结果数量上限 10
threshold 相似度阈值 0.2
index_names 要检索的知识库名称列表(可选) -
kb_page / kb_page_size 分页拉取 DataMate 知识库列表 -

搜索参数:query 必填。返回结果包含文件名、下载 URL 与分数。实现类 DataMateSearchTool 位于 datamate_search_tool.py,通过 DataMateCore 访问后端。

dify_search:Dify 知识库检索

配置参数:

参数 说明
dify_api_base Dify API 基础地址,见下方三种部署形态
api_key Dify 知识库 API 密钥,以 dataset- 开头(在 Dify 知识库页面 → API 标签页 → API Keys 按钮创建)
dataset_ids 数据集 ID 列表,例如 ["e912e1f5-29c0-40da-8baf-d35da77c60df"](在 Dify 知识库页面 URL 中可找到)
top_k 返回结果数量上限,默认 3

dify_api_base 的三种部署形态对应不同取值:

  • 本地部署 Dify:直接使用 http://host.docker.internal/v1;
  • 服务器部署 Dify:使用 http://x.x.x.x:x/v1,替换为实际 IP 与端口;
  • Dify 官方云服务:直接使用 https://api.dify.ai/v1。

搜索参数:query 必填;search_method 可选 keyword_search、semantic_search、full_text_search、hybrid_search,默认 semantic_search。返回标题、内容、分数等。实现类 DifySearchTool(dify_search_tool.py)还支持 rerank / rerank_model_name 可选配置,默认 rerank=False。

另外,datamate_search 与 dify_search 在服务端实例化时(tool_configuration_service.py)同样会按配置注入 rerank_model,即三者共享同一套"检索 + 可选重排序"增强链路。

五、公共网络搜索:exa_search / tavily_search / linkup_search

三个工具分别对接 Exa、Tavily、Linkup 三家网络检索服务,用于实时资讯、开放网络证据与通用知识的获取。三者的配置形态高度一致。

配置参数

参数 说明 默认值
exa_api_key / tavily_api_key / linkup_api_key 对应服务的 API 密钥 必填
max_results 返回结果数量上限 5
image_filter 是否启用图片过滤 True

搜索参数

  • query(必填):搜索查询词。

行为细节与密钥获取

  • 图片过滤:默认开启,自动剔除不相关图片;可关闭以返回原始图片 URL。关闭后返回结果中包含去重后的图片 URL 列表。
  • 返回内容:标题、URL、摘要以及可选的图片 URL(已去重)。

从源码实现看:

  • exa_search_tool.py 使用 Exa(api_key=...) 客户端,max_results 限幅 1~100,image_filter 默认 True;调用 exa.search_and_contents() 时开启 livecrawl="always",并在 extras 中请求图片链接("image_links": 10),文本片段上限 max_characters: 2000;
  • tavily_search_tool.py 使用 TavilyClient,配置与 Exa 对齐;
  • linkup_search_tool.py 使用 LinkupClient,同样支持 image_filter 默认开启。

密钥获取途径(在对应服务控制台创建):

  • Exa:在 exa.ai 注册后于控制台创建 EXA API Key;
  • Tavily:在 tavily.com 注册后从 Dashboard 获取 Tavily API Key;
  • Linkup:在 linkup.so 注册后在账户中创建 Linkup API Key。

需要说明的是,这些密钥属于敏感凭据,应存放于平台安全配置中,不应写入提示词或工具描述。

六、How to Use:七步上手路径

将上述工具接入 Agent 并投入使用,官方文档给出如下七步流程:

  1. 选择数据源:私有数据用 knowledge_base_search、aidp_search、datamate_search 或 dify_search;公开信息用 Exa / Tavily / Linkup。
  2. 调节模式与数量:知识库检索切换 search_mode(本地)或 search_method(AIDP/Dify);公共搜索调节 max_results 与图片过滤开关。
  3. 填充连接与认证参数:AIDP 需要 server_url、api_key、tenant_id——先在平台安全配置中填写,并运行一次测试连接验证连通性。
  4. 圈定可检索知识库范围:AIDP 在工具配置中使用 kds_list 指定默认 KB;实际检索还会被当前聊天用户的 AIDP 权限白名单二次过滤。
  5. 收窄查询:本地 KB 提供 index_names、AIDP 提供显式 kds_list 来限定范围;DataMate 通过调节 top_k 与 threshold 控制精度。
  6. 可选重排序:设置 enable_rerank: true 或 reranking_enable: true,并调优重排序模型/模式参数以提升相关性。
  7. 消费结果:工具输出 JSON,可直接用于答案生成或摘要总结,并携带引用索引便于标注来源。

七、安全与最佳实践

  • 凭据安全:公共搜索与 AIDP 的 api_key 等凭据一律存放于平台安全配置,绝不暴露在提示词中。这一点在服务端实现上也有强制约束——aidp_search 的凭据由进程环境变量注入(AIDP_SERVER_URL / AIDP_API_KEY / AIDP_TENANT_ID),客户端提交的凭据不会被信任。
  • 权限边界:AIDP 检索尊重当前聊天用户的权限。即使 KB 在工具的 kds_list 中,若用户无权限也不会被返回——需要联系 AIDP 管理员授权。过滤后无可用 KB 时会返回明确的"无权限"提示而非静默空结果。
  • 数据时效:查询前先同步知识库内容,避免基于过期数据作答。
  • 查询质量:查询过宽时拆分或缩短查询词;图片被过度过滤时,可关闭过滤查看原始 URL 再做判断。

八、总结

Nexent 的 Search Tools 以"一个统一工具框架、两类数据源、七个内置实现"的方式,覆盖了从私有知识库到公共网络的完整检索需求:knowledge_base_search 负责本地多模式检索,aidp_search 通过 FusionSearch 提供带权限白名单与重排序的多模态企业检索,datamate_search 与 dify_search 打通第三方知识库资产,Exa / Tavily / Linkup 三个网络工具补齐实时公开信息能力。结合 sdk/nexent/core/tools/ 与 backend/services/tool_configuration_service.py 的源码可见,每个工具都经过参数校验、凭据注入与可选的 rerank 增强,既可直接在平台界面配置,也经受了服务端测试连接逻辑的验证。按本文的参数表与七步流程配置,即可让 Agent 稳定获得高质量、可溯源、带权限约束的检索能力。

登录后查看全文
nexent