Nexent 搜索工具(Search Tools)全解析:本地知识库、AIDP 多模态检索与公共网络搜索的配置与实战指南
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 约束)。
权限方面有两个重要行为:
- 检索范围受当前聊天用户的 AIDP 权限白名单过滤:无论使用默认
kds_list还是 LLM 提供的kds_list,都会与用户可访问的 KB 集合取交集,未授权 KB 被静默丢弃; - 过滤后若无任何可访问 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 并投入使用,官方文档给出如下七步流程:
- 选择数据源:私有数据用
knowledge_base_search、aidp_search、datamate_search或dify_search;公开信息用 Exa / Tavily / Linkup。 - 调节模式与数量:知识库检索切换
search_mode(本地)或search_method(AIDP/Dify);公共搜索调节max_results与图片过滤开关。 - 填充连接与认证参数:AIDP 需要
server_url、api_key、tenant_id——先在平台安全配置中填写,并运行一次测试连接验证连通性。 - 圈定可检索知识库范围:AIDP 在工具配置中使用
kds_list指定默认 KB;实际检索还会被当前聊天用户的 AIDP 权限白名单二次过滤。 - 收窄查询:本地 KB 提供
index_names、AIDP 提供显式kds_list来限定范围;DataMate 通过调节top_k与threshold控制精度。 - 可选重排序:设置
enable_rerank: true或reranking_enable: true,并调优重排序模型/模式参数以提升相关性。 - 消费结果:工具输出 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 稳定获得高质量、可溯源、带权限约束的检索能力。