Nexent 搜索工具完全指南:本地知识库、AIDP/DataMate/Dify 与公网搜索的配置与实战

原创2026-10-14 23:22:201,963 阅读
文章标签:AI Agent人工智能大模型AI 应用多智能体Agent 框架Agent 编排工具调用AI 技能MCP 服务Agent 记忆RAG后端前端低代码

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 格式、可直接用于回答或摘要,配合引用标记便于在最终答案中逐条溯源。

配置与使用流程(七步实操)

  1. 选择数据源:私有资料用 knowledge_base_search、aidp_search、datamate_search 或 dify_search;实时公开信息用 Exa/Tavily/Linkup。入口为「Agent 开发 → 选择 Agent 工具 → 找到对应工具 → 打开配置」。
  2. 设置检索模式/数量:知识库工具在 search_mode / search_method 之间切换(如本地库选 hybrid/accurate/semantic,Dify 选 semantic_search/hybrid_search 等);公网搜索调整 max_results 与是否启用图片过滤。
  3. 填写连接与鉴权参数:aidp_search 必须准确填写 server_url、api_key 与 tenant_id;datamate_search 填写 server_url 并按需调整 verify_ssl;dify_search 填写 dify_api_base、api_key 与 dataset_ids。建议先在平台安全配置中完成测试连接,确认连通后再保存。
  4. 配置可检索知识库范围:AIDP 在工具配置中通过 kds_list 勾选默认检索的知识库;实际调用时还会按当前对话用户的 AIDP 权限白名单二次过滤,用户无权限的 KB 即使配置了也不会被检索到,需要联系 AIDP 管理员授权。
  5. 限定本次检索范围:需要特定知识库时,填写 index_names(本地知识库,支持显示名)或显式传入 kds_list(AIDP),避免无关结果混入;DataMate 可通过 threshold 与 top_k 控制结果精度与数量。
  6. 按需启用重排序:本地库/DataMate/Dify 设置 enable_rerank: true 并指定 rerank_model;AIDP 设置 reranking_enable: true,并通过 reranking_mode(performance / high_accuracy)调整效果。开启后初检候选自动放大(×10),精排择优返回。
  7. 消费结果:返回为 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 工具创建链路 中工具实例的装配逻辑。

登录后查看全文
nexent