Nexent 搜索工具完全指南:本地知识库、AIDP/DataMate/Dify 与公网搜索的配置与实战
Nexent 搜索工具完全指南:本地知识库、AIDP/DataMate/Dify 与公网搜索的配置与实战
本文是 Nexent 平台「搜索工具组」的完整技术指南。搜索工具组覆盖本地知识库(knowledge_base_search)、AIDP 企业级知识库(aidp_search)、DataMate 知识库(datamate_search)、Dify 知识库(dify_search)以及 Exa / Tavily / Linkup 三大公网搜索服务,适用于实时信息查询、行业资料检索、私有文档查找和企业级多模态知识库检索等场景。读完本文,你将掌握:每个工具的完整配置参数与默认值、底层检索与重排序原理、多模态双通道输出机制、权限白名单过滤逻辑,以及一套可直接落地的配置与排错流程。
本文主体依据 官方英文文档 与 官方中文文档,并结合 Nexent SDK 工具源码与后端配置服务展开源码级解析;搜索工具属于 本地工具总览 中「Search Tools」分类,其余文件、邮件、多模态、终端、SQL 工具可参见该总览目录。
工具全景与适用场景
Nexent 的搜索工具全部实现为继承自 smolagents.tools.Tool 的工具类,统一在 SDK 工具注册表 中导出,按能力分为两类:
| 工具 | 数据源 | 核心用途 | SDK 实现类 |
|---|---|---|---|
knowledge_base_search |
Nexent 本地知识库 | 私有文档、领域知识检索,支持多知识库与多检索模式 | KnowledgeBaseSearchTool |
aidp_search |
AIDP 企业知识库 | 文本/表格/图片多模态 FusionSearch 检索 | AidpSearchTool |
datamate_search |
DataMate 知识库 | DataMate 私有库检索 | DataMateSearchTool |
dify_search |
Dify 知识库 | Dify 数据集检索 | DifySearchTool |
exa_search |
Exa 公网搜索 | 实时网页与图片搜索 | ExaSearchTool |
tavily_search |
Tavily 公网搜索 | 网页与图片搜索 | TavilySearchTool |
linkup_search |
Linkup 公网搜索 | 图文混合搜索 | LinkupSearchTool |
典型使用场景:
- 查询内部文档、技术规范、行业资料:
knowledge_base_search、datamate_search、dify_search; - 检索企业 AIDP 知识库中的多模态资料(文档、表格、图片、技术图纸等):
aidp_search; - 获取最新新闻、数据或网页证据:
exa_search/tavily_search/linkup_search; - 在答案中附带图片参考:开启图片过滤后,搜索结果可同步输出图片 URL 列表。
从后端视角看,这些工具在 工具配置服务 中通过 get_local_tools() 自动扫描注册:SDK 工具类构造函数的 Field(...) 默认值、ge/le 约束以及中英文描述会被提取并持久化到工具库表,随后出现在平台的「选择 Agent 工具」配置面板中。内置标签方面,内置工具标签 将 tavily_search、exa_search、linkup_search、knowledge_base_search 归类为 search,将 dify_search、datamate_search、aidp_search 归类为 knowledge-base,便于按标签批量筛选工具。
本地知识库检索:knowledge_base_search
knowledge_base_search 是面向 Nexent 本地知识库的核心检索工具,实现类为 KnowledgeBaseSearchTool(见 knowledge_base_search_tool.py)。
配置参数(Configuration Parameters)
| 参数 | 说明 | 默认值 / 约束 |
|---|---|---|
top_k |
返回搜索结果的最大数量 | 默认 3,取值范围 1–100(源码 Field(default=3, ge=1, le=100)) |
index_names |
要检索的知识库名称列表,可用用户侧显示名或内部索引名 | 可选,不配置时使用 Agent 已绑定的知识库 |
search_mode |
检索模式 | hybrid(默认,混合召回)、accurate(文本精确/模糊匹配)、semantic(向量语义) |
enable_rerank |
是否启用重排序 | 默认 False,开启后对初检结果二次排序 |
rerank_model |
重排序使用的模型 | 默认为系统配置的 rerank 模型,enable_rerank 为 True 时生效 |
检索参数(Search Parameters)
query:检索问题,必填;search_mode:hybrid(默认)、accurate、semantic;index_names:本次调用指定要搜索的知识库名称列表(可选),支持用户侧显示名或内部索引名。
三种检索模式与底层实现
源码 _run_search() 按 search_mode 分发到三个检索方法:
hybrid(混合召回):调用self.vdb_core.hybrid_search(...),同时融合向量语义与文本匹配信号,并携带得分明细(include_scores=True会合并scores与检索高亮词retrieval_highlight_terms到score_details);accurate(精确/模糊匹配):调用self.vdb_core.accurate_search(...),偏向文本层面匹配;semantic(向量语义):调用self.vdb_core.semantic_search(...),基于 embedding 模型做向量召回。
传入非法模式时工具会直接抛出异常:Invalid search mode: xxx, only support: hybrid, accurate, semantic。
重排序(Rerank)的候选放大机制
开启 enable_rerank 后,工具会先用放大后的 top_k 做初检,再交给 rerank 模型精排,从而保证「初检不漏、精排择优」。放大倍数定义在 constants.py:RERANK_OVERSEARCH_MULTIPLIER = 10,即初检候选数 = top_k × 10,随后 rerank_model.rerank(query, documents, top_n=len(documents)) 对全部候选打分,再截取前 top_k 返回。若 rerank 失败,代码会记录告警并回退到原始检索结果(Reranking failed, using original results),保证可用性。
名称转换与检索范围解析
工具内部维护 display_name_to_index_map(知识库显示名 → ES 索引名)映射:
- LLM 传入
index_names时,_convert_to_index_names()会把用户侧显示名转换为真实索引名再查询; - 返回结果给模型时,
_convert_to_display_names()再将内部索引名转回显示名,保证模型看到的是可读名称。
检索范围由 _resolve_search_scope() 统一解析:先取工具配置的知识库集合,再与后端注入的 allowed_index_names 权限白名单取交集;若本次调用显式传了 index_names,则以本次指定为准,并区分「无权限(permission_denied_scope)」「未配置/不可用(unavailable_scope)」两类被过滤项。当过滤后没有可访问知识库时,工具不会静默返回空结果,而是返回明确的 NOTICE 提示(如 No configured knowledge bases are accessible, so search was not executed),该逻辑封装在 统一检索消息模块 的 resolve_knowledge_search_scope() 与 build_knowledge_search_response() 中,knowledge_base_search 与 aidp_search 共用这套范围解析与提示协议。
返回结果字段
返回每条匹配片段包含:标题(title)、路径/URL(url)、来源类型(source_type)、得分(score)、得分明细(score_details) 等;本地 local/minio 来源会被归一化为 file。若未选择任何知识库,工具会提示「无可用知识库」。此外,命中图片类文档(process_source == "UniversalImageExtractor")时,图片 URL 会随 PICTURE_WEB 通道输出(详见下文「统一结果格式与双通道输出」)。
该工具的完整行为(三种模式、rerank 生效与回退、名称转换、来源类型归一化、图片通道)均有对应单元测试,参见 test_knowledge_base_search_tool.py。
AIDP 企业知识库检索:aidp_search
aidp_search 通过 AIDP 平台的 FusionSearch API 实现企业级多模态知识库检索,实现类为 AidpSearchTool(见 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 |
默认检索的知识库 ID(kds_id)列表,以 JSON 字符串数组保存(如 ["aidp-kb-01", "aidp-kb-02"]) |
可选,最多 10 个(源码 _MAX_KDS = 10),决定该工具默认访问哪些 AIDP 知识库 |
search_method |
搜索方法 | hybrid_search(默认,融合检索)、vector_search(向量检索)、full_text_search(全文检索) |
reranking_enable |
是否启用重排序 | 默认 True |
reranking_mode |
重排序模式 | performance(默认)/ high_accuracy |
rewrite_enable |
是否启用查询改写(黑话改写) | 默认 False |
related_search_enable |
是否启用关联 Chunk 检索 | 默认 False |
score_threshold |
相似度阈值 | 默认 0.0,取值范围 0–1 |
top_k |
返回结果数量 | 默认 10,取值范围 1–100 |
multi_modal |
是否返回多模态 Chunk(图片/表格) | 默认 True |
源码在初始化时会对参数做严格校验:server_url、api_key、tenant_id 缺一即抛 ValueError;search_method 与 reranking_mode 非法时自动回退到默认值并记录告警;kds_list 必须是合法 JSON 数组且长度不超过 10。
检索参数
query:检索问题,必填;kds_list:可选,本次调用指定要检索的知识库 ID 列表,不传则使用工具配置中的默认kds_list。
底层调用链与容错重试
工具实际请求的端点为:
POST {server_url}/KnowledgeBase/Tenants/{tenant_id}/Retrieval/FusionSearch
请求体包含 query、kds_list、search_method、reranking_enable、rewrite_enable、related_search_enable、score_threshold、top_k、multi_modal(启用 rerank 时追加 reranking_mode),鉴权头为 Authorization: Bearer {api_key}。
针对 AIDP FusionSearch 网关偶发的瞬时故障,源码实现了指数退避自动重试:对 502/503/504 状态码最多重试 3 次(_AIDP_SEARCH_MAX_ATTEMPTS = 3),退避间隔依次为 0.5s、1.5s;重试耗尽后,若是 503 会返回面向用户的可读提示——通常是「所选知识库还没有可索引内容(知识库为空或仍在索引中),请上传文档并等待索引完成后再试」,而不是抛出原始 httpx 异常串。
多模态双通道输出与图片安全机制
aidp_search 返回文本、表格、图片等多模态检索块(Chunk),并通过双通道输出:
- 所有块(文本/表格/图片)通过
SEARCH_CONTENT通道发送,供模型阅读与引用; - 图片另通过
PICTURE_WEB通道发送图片 URL,供前端渲染。
这里有一个关键的安全设计:AIDP 返回的图片 file_url 是相对路径(如 aidp-kb-1/data/img.png),真实图片需要携带 Bearer token 才能获取。因此工具会将其拼装为完整 URL({base_url}/KnowledgeBase/Tenants/{tenant_id}/KnowledgeBases/{file_url})并通过图片代理通道投递,绝不把带鉴权的原始图片 URL 暴露给 LLM——模型在回答中只会使用一个安全的 Markdown 图片标记(形如 AIDP image),由前端按标记渲染。同时,Chunk 文本中的 <img> HTML 标签会被正则剥离,避免无效引用。这是「结果可直接用于生成答案」与「凭证不外泄」两者兼得的实现细节。
权限白名单过滤
aidp_search 的检索范围会按当前对话用户的 AIDP 权限白名单过滤:
- 无论使用配置默认的
kds_list还是 LLM 本次传入的kds_list,都会与「用户有权访问的知识库集合」取交集,未授权 KB 会被静默剔除; - 后端在构造工具配置时通过
set_allowed_kds()注入白名单(包括空集合 =「用户无任何权限」的特殊语义),并支持kds_name→kds_id的显示名转换; - 若过滤后无可访问知识库,工具会返回明确的无权限 NOTICE(
no read permission: [...]),而不是静默返回空结果或直接请求 AIDP 端点。
该白名单的后端侧实现在 工具配置服务 中:读取工具配置(search_tool_info_impl)与更新 kds_list(update_tool_info_impl)时都会调用 resolve_current_aidp_access() 解析 AIDP 权限快照,配置中混入用户无权访问的 KB 会被拦截并抛出「用户无权配置该知识库」的校验错误。
DataMate 知识库检索:datamate_search
datamate_search 对接 DataMate 知识库,实现类为 DataMateSearchTool(见 datamate_search_tool.py)。
配置参数
| 参数 | 说明 | 默认值 / 约束 |
|---|---|---|
server_url |
DataMate 服务地址,如 http://192.168.1.100:8080 或 https://datamate.example.com:8443 |
必填,必须带 http:// 或 https:// 前缀 |
verify_ssl |
是否验证 HTTPS 连接的 SSL 证书 | 不填时:HTTPS 默认不验证(适配自签名证书),HTTP 默认验证;显式设置后以设置值为准 |
index_names |
要检索的知识库名称列表 | 可选,不配置时返回「未选择知识库」提示 |
top_k |
返回结果数量 | 默认 3(源码 Field(default=3, ge=1, le=100)) |
threshold |
相似度阈值 | 默认 0.2,取值范围 0.0–1.0 |
kb_page / kb_page_size |
分页获取 DataMate 知识库列表的页码与页大小 | 默认 1 / 20(页大小上限 100) |
enable_rerank / rerank_model |
重排序开关与模型 | 默认关闭;开启后初检候选同样按 top_k × RERANK_OVERSEARCH_MULTIPLIER 放大 |
server_url 解析与 SSL 语义
源码在初始化时对 server_url 做了完整解析(_parse_server_url()):要求必须包含协议前缀,缺失协议、非法主机名、端口超出 1–65535 都会抛 ValueError;未显式指定端口时,https 默认 443、http 默认 80。verify_ssl 的默认语义与 HTTPS 场景直接相关——对自签名证书的 HTTPS 服务默认不做证书校验,而对 HTTP 服务始终校验,这正好对应内网/私有化部署 DataMate 的常见形态。
检索参数与结果
query:检索问题,必填;- 返回结构化结果,包含:文件名(file_name)、文本内容、下载链接(download_url)、得分(score)、得分明细(score_details);
- 得分明细中会附加
datamate_dataset_id、datamate_file_id、datamate_download_url、datamate_base_url,方便溯源; - 未选择知识库时返回 JSON 字符串
"No knowledge base selected. No relevant information found.";无结果时抛出「Try a less restrictive/shorter query」类提示。
相关单元测试覆盖了 URL 解析(http/https、默认端口、非法格式)、SSL 验证行为、metadata 解析、多知识库检索与 rerank 启停,见 test_datamate_search_tool.py。
Dify 知识库检索:dify_search
dify_search 对接 Dify 知识库(数据集),实现类为 DifySearchTool(见 dify_search_tool.py)。
配置参数
| 参数 | 说明 | 默认值 / 约束 |
|---|---|---|
dify_api_base |
Dify API 基础地址 | 必填,三种部署形态见下 |
api_key |
Dify 知识库 API 密钥,以 dataset- 开头 |
必填(在 Dify 知识库页面 → 左上角「API」页签 → 右上角「API 密钥」按钮创建) |
dataset_ids |
知识库(数据集)ID 列表,如 ["e912e1f5-29c0-40da-8baf-d35da77c60df"] |
必填,可为 JSON 字符串数组或数组(可在 Dify 知识库页面 URL 中查看知识库 ID) |
top_k |
每个数据集返回的结果数量 | 默认 3(1–100) |
search_method |
搜索方法 | semantic_search(默认)、keyword_search、full_text_search、hybrid_search |
enable_rerank / rerank_model |
重排序开关与模型 | 默认关闭 |
dify_api_base 三种部署形态:
- 本地 Docker 部署 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。
工具对每个 dataset_id 依次调用 Dify 检索接口:
POST {server_url}/datasets/{dataset_id}/retrieve
请求体为 query + retrieval_model(含 search_method、top_k、score_threshold 等),鉴权头为 Authorization: Bearer {api_key}。检索到文档后,工具还会批量调用:
GET {server_url}/datasets/{dataset_id}/documents/{document_id}/upload-file
获取每个文档的下载 URL 并映射到对应结果上,因此 dify_search 返回的每条结果都包含标题(取自文档名)、内容片段、得分与可下载的文档链接。参数缺失(server_url、api_key、dataset_ids 为空或非法 JSON)会在初始化阶段直接报错,相关行为均有单测覆盖,见 test_dify_search_tool.py。
公网搜索三件套:exa_search / tavily_search / linkup_search
三个公网搜索工具面向开放互联网,分别对接 Exa、Tavily、Linkup 三家搜索服务,实现类见 exa_search_tool.py、tavily_search_tool.py、linkup_search_tool.py。
配置参数(三者一致)
| 参数 | 说明 | 默认值 / 约束 |
|---|---|---|
exa_api_key / tavily_api_key / linkup_api_key |
对应服务的 API 密钥 | 必填,应配置在平台安全配置中 |
max_results |
返回结果数量 | 默认 3(源码 Field(default=3, ge=1, le=100),英文文档标注为 5,以源码默认值为准) |
image_filter |
是否启用图片过滤 | 默认 True |
检索参数
query:检索问题,必填。
三家服务的实现差异
- Exa:使用
exa_py客户端调用search_and_contents(query, text={"max_characters": 2000}, livecrawl="always", extras={"links": 0, "image_links": 10}, num_results=max_results),返回标题、URL、正文摘要(最多 2000 字符)与发布/抓取日期; - Tavily:使用
TavilyClient.search(query, max_results=..., include_images=True),从响应中同时取出results与images列表; - Linkup:使用
LinkupClient.search(query, depth="standard", output_type="searchResults", include_images=True),结果区分为LinkupSearchTextResult(文本结果)与LinkupSearchImageResult(纯图片结果),图片结果的文本统一标记为This is a pure image result。
三者都返回标题、URL、摘要,并可能附带图片 URL 列表(已去重);无结果时统一提示「Try a less restrictive/shorter query」。
图片过滤机制
image_filter 默认开启:工具会把图片 URL 列表提交给平台的数据处理服务(POST {DATA_PROCESS_SERVICE}/tasks/filter_important_image),以查询词作为正向提示词、以 logo or banner or background or advertisement or icon or avatar 作为负向提示词,并发(信号量上限 10)判断图片是否与查询相关,仅保留 is_important=true 的图片。过滤失败时会回退为原始图片列表,保证不丢结果。若关闭 image_filter,则原始(去重后的)图片 URL 列表直接通过 PICTURE_WEB 通道输出,便于人工复核。
API Key 获取途径
- Exa:在 exa.ai 注册,于控制台创建 EXA API Key;
- Tavily:在 tavily.com 注册,从 Dashboard 获取 Tavily API Key;
- Linkup:在 linkup.so 注册,于个人中心创建 Linkup API Key。
统一结果格式与双通道输出
所有搜索工具的结果都收敛到统一的消息结构 SearchResultTextMessage(定义于 统一检索消息模块),字段包括 title、url、text、published_date、source_type、filename、score、score_details、cite_index、search_type、tool_sign。面向大模型的简化格式会自动生成引用标记:index = "{tool_sign}{cite_index}",reference_mark = "[[index]]",例如 [[a1]]、[[b3]],其中 tool_sign 用于区分检索来源(a 本地知识库、b Exa、c Linkup、d Tavily、e DataMate、g Dify、j AIDP)。
工具运行过程中通过 MessageObserver 向流式通道推送三类消息(通道枚举见 observer.py):
CARD:运行卡片,如[{"icon": "search", "text": query}],前端渲染搜索状态;SEARCH_CONTENT:全部检索结果的结构化 JSON,供模型阅读与最终总结;PICTURE_WEB:图片 URL 列表({"images_url": [...]}),前端直接渲染。
因此搜索结果是 JSON 格式、可直接用于回答或摘要,配合引用标记便于在最终答案中逐条溯源。
配置与使用流程(七步实操)
- 选择数据源:私有资料用
knowledge_base_search、aidp_search、datamate_search或dify_search;实时公开信息用 Exa/Tavily/Linkup。入口为「Agent 开发 → 选择 Agent 工具 → 找到对应工具 → 打开配置」。 - 设置检索模式/数量:知识库工具在
search_mode/search_method之间切换(如本地库选hybrid/accurate/semantic,Dify 选semantic_search/hybrid_search等);公网搜索调整max_results与是否启用图片过滤。 - 填写连接与鉴权参数:
aidp_search必须准确填写server_url、api_key与tenant_id;datamate_search填写server_url并按需调整verify_ssl;dify_search填写dify_api_base、api_key与dataset_ids。建议先在平台安全配置中完成测试连接,确认连通后再保存。 - 配置可检索知识库范围:AIDP 在工具配置中通过
kds_list勾选默认检索的知识库;实际调用时还会按当前对话用户的 AIDP 权限白名单二次过滤,用户无权限的 KB 即使配置了也不会被检索到,需要联系 AIDP 管理员授权。 - 限定本次检索范围:需要特定知识库时,填写
index_names(本地知识库,支持显示名)或显式传入kds_list(AIDP),避免无关结果混入;DataMate 可通过threshold与top_k控制结果精度与数量。 - 按需启用重排序:本地库/DataMate/Dify 设置
enable_rerank: true并指定rerank_model;AIDP 设置reranking_enable: true,并通过reranking_mode(performance/high_accuracy)调整效果。开启后初检候选自动放大(×10),精排择优返回。 - 消费结果:返回为 JSON,可直接用于回答、摘要或后续引用;每条结果带
cite_index/reference_mark,便于在答案中标注引用。
安全与最佳实践
- 凭证安全:公网搜索(Exa/Tavily/Linkup)与 AIDP 等外部服务的
api_key必须配置在平台的安全配置中,绝不能出现在对话或提示词里;AIDP 图片 URL 由系统经鉴权代理通道投递,不向模型暴露原始带凭证地址。 - 权限边界:AIDP 知识库检索严格受当前对话用户权限控制。用户看不到的 KB,即使位于工具
kds_list配置中也不会被检索;过滤后无可访问知识库时会返回明确的无权限提示而非静默空结果。knowledge_base_search同样具备后端注入的知识库白名单(allowed_index_names),防御 LLM 伪造参数越权访问。 - 数据新鲜度:知识库检索前确认已同步最新文档,避免基于旧版本内容作答;AIDP 检索若遇 503,多半是所选知识库尚无已索引内容,先上传文档并等待索引完成再重试。
- 查询调优:查询过于宽泛导致无结果时,缩短或拆分问题;图片过滤未命中时,可关闭
image_filter获取原始图片列表人工复核。 - 部署形态:
dify_search的dify_api_base需按部署形态(本地 Docker / 服务器 / 云服务)选择对应地址;datamate_search对自签名证书 HTTPS 默认关闭证书校验,仅适用于内网可信环境。
以上参数、默认值与行为均可直接在对应 SDK 源码与后端配置服务中核对;需要进一步了解搜索工具在 Agent 运行时的挂载方式,可继续阅读 本地工具总览 或查阅 Agent 工具创建链路 中工具实例的装配逻辑。