WeKnora 知识搜索 API 完全指南从请求参数到检索结果的源码级解析【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnoraWeKnora 的POST /api/v1/knowledge-search接口提供了一条纯检索、不经过 LLM 总结的知识搜索通道输入查询文本直接在知识库中召回相关分块chunk返回按相关性排序的检索结果。本文以官方 API 文档 docs/api/knowledge-search.md 为主体结合仓库中该接口的请求结构体、Handler 实现与检索/重排链路源码系统讲解请求参数、返回字段、resource_urls直链机制以及底层的校验与检索原理帮助你把这个接口集成进自己的应用或脚本。接口概览方法路径描述POST/api/v1/knowledge-search在知识库中搜索相关内容不使用 LLM 总结直接返回检索结果该接口属于 WeKnora 的知识搜索分类完整 API 清单见 docs/api/README.md适用于以下典型场景需要把检索结果作为结构化数据用于二次处理例如喂给自定义的提示词模板、构建下游管线需要在发问前先定位证据片段人工确认检索质量需要跨多个知识库或限定到特定文件进行范围化检索。与knowledge-chat等问答接口不同知识搜索不会调用大模型生成答案因此响应延迟更低、返回内容完全可控便于做检索评估与调试。请求参数详解请求体JSON Body字段类型必填说明querystring是搜索查询文本knowledge_base_idstring否单个知识库 ID向后兼容与knowledge_base_ids互斥knowledge_base_idsstring[]否多个知识库 ID 列表跨知识库搜索knowledge_idsstring[]否进一步限定到指定知识文件不传则在整库范围内搜索必须指定knowledge_base_id或knowledge_base_ids中的至少一个。从源码看接口的请求结构体定义在 internal/handler/session/types.go#L72-L80// SearchKnowledgeRequest defines the request structure for searching knowledge without LLM summarization type SearchKnowledgeRequest struct { Query string json:query binding:required // Query text to search for KnowledgeBaseID string json:knowledge_base_id // Single knowledge base ID (for backward compatibility) KnowledgeBaseIDs []string json:knowledge_base_ids // IDs of knowledge bases to search (multi-KB support) KnowledgeIDs []string json:knowledge_ids // IDs of specific knowledge (files) to search TagIDs []string json:tag_ids // Tag IDs for filtering within a single KB MentionedItems []MentionedItemRequest json:mentioned_items // Optional scoped tag mentions }值得注意的是结构体中还存在官方 markdown 文档未展开列出的两个字段从源码注释可以确认其语义tag_idsstring[]在单个知识库内按标签 ID 过滤mentioned_items[]MentionedItemRequest可选的带作用域的标签提及scoped tag mentions用于把检索范围进一步收窄到某些标签上下文。查询参数Query Stringresource_urls取值为handle默认或public。public会把检索结果content/image_info里的resource://引用替换为可加载的 http(s) 链接详见 docs/api/README.md#文件与图片引用resource-与直链。请求示例官方文档给出了三种典型调用这里完整保留并补充说明# 搜索单个知识库 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_base_id: kb-00000001 } # 搜索多个知识库 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_base_ids: [kb-00000001, kb-00000002] } # 搜索指定文件knowledge_ids 与知识库参数配合使用 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_ids: [4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5] }三个要点认证所有请求需要在 HTTP 请求头携带X-API-Key获取方式见 docs/api/README.md 的认证机制一节为便于追踪问题官方还建议附带X-Request-ID请求头。基础 URL接口挂在/api/v1前缀之下完整路径为http://localhost:8080/api/v1/knowledge-search。单库与多库互斥语义knowledge_base_id是为旧客户端保留的单数形式。在 Handler 实现中internal/handler/session/qa.go#L809-L823服务端会把knowledge_base_id合并进knowledge_base_ids列表并做去重因此两者同时传入也不会重复检索只是单数形式最终统一按多库逻辑处理。响应格式与字段说明完整响应示例{ data: [ { id: chunk-00000001, content: 知识库是用于存储和检索知识的系统..., knowledge_id: knowledge-00000001, chunk_index: 0, knowledge_title: 知识库使用指南, start_at: 0, end_at: 500, seq: 1, score: 0.95, chunk_type: text, image_info: , metadata: {}, knowledge_filename: guide.pdf, knowledge_source: file } ], success: true }响应字段说明data[]字段类型说明idstring分块 IDcontentstring命中的分块文本knowledge_idstring该分块所属的知识 IDchunk_indexint分块在知识中的序号knowledge_titlestring来源知识标题start_at / end_atint分块在源文档中的字符偏移seqint命中排序号scorenumber相似度rerank 后归一化后的最终得分chunk_typestring分块类型text/image/ ...image_infostring图像分块的额外信息JSON 字符串metadataobject自定义元数据knowledge_filenamestring来源文件名knowledge_sourcestring来源类型file/url/manual几个容易忽略的细节start_at/end_at是分块在源文档中的字符偏移区间可用于在原文中定位命中片段chunk_type为image时image_info会携带图像的额外信息JSON 字符串配合resource://引用或resource_urlspublic直链即可加载图片knowledge_source标识知识的来源形态file上传文件、url网页采集、manual手工录入。请求校验与执行链路源码视角在 Handler 层SearchKnowledge的实现位于 internal/handler/session/qa.go#L781其执行顺序可以归纳为四步每一步都能在源码中找到对应逻辑解析与空校验c.ShouldBindJSON(request)解析请求体随后显式检查Query是否为空为空直接返回 400Query content cannot be empty。解析 resource_urls先解析存储引用表示方式handle/public如果传了非法值或当前凭证不允许public模式会在这里提前拒绝避免浪费后续检索开销——源码注释明确说明这是在检索前解析让拼写错误或被拒绝的作用域不产生代价。向后兼容合并与作用域校验把单数knowledge_base_id合并进knowledge_base_ids对tag_ids/mentioned_items做去重与作用域校验validateUnscopedTagIDs、mergeTagScopesFromRequestIDs。目标合法性校验如果knowledge_base_ids、knowledge_ids、标签作用域全部为空返回 400At least one knowledge_base_id, knowledge_base_ids, knowledge_ids, or scoped tag must be provided随后通过types.AuthorizeTenantAPIKeyKnowledgeTargets校验当前 API Key 是否有权访问这些检索目标。从路由注册看该接口定义在 internal/router/routes_chat.go#L127knowledgeSearch : g.apiKeyGroup(r.Group(/knowledge-search, g.Viewer()), apiKeyRetrieve(apiKeyFullAccess()))其中g.Viewer()表明访问者级别Viewer即可调用apiKeyRetrieve(apiKeyFullAccess())则用于取出并鉴权 API Key——这也意味着限定知识库范围的 API Key 在权限控制上有着更细的约束详见下文注意事项。检索与重排Rerank原理知识搜索返回的score字段标注为rerank 后归一化后的最终得分其背后的重排逻辑在 Agent 侧的检索工具中有完整的对应实现位于 internal/agent/tools/knowledge_search.go召回后先去重deduplicateResults在重排前对多路召回结果做去重降低重排开销多查询合并当存在多个查询子句时取第一个查询作为重排查询或用空格拼接多个查询strings.Join(queries, )重排模型可用时调用rerankResults对召回结果打分重排并按阈值rerankThreshold()过滤重排失败时优雅降级——源码注释明确说明A failed rerank call degrades to the raw retrieval order即直接退回原始检索顺序保证接口可用性重排后二次去重因为重排可能改变分数与顺序代码在重排之后还会再做一次最终去重避免重复项残留MMR 阶段注释中还提到结果会经过 MMRMaximal Marginal Relevance处理兼顾相关性relevance与多样性diversity。也就是说一次知识搜索的完整数据流是多路召回 → 去重 → Rerank 重排可选失败降级→ 阈值过滤 → 最终去重 → 按得分排序输出。score反映的是重排模型归一化后的相关度分数seq则是命中在最终结果中的排序号。关于resource_urlspublic直链的重要注意事项resource_urls查询参数的控制逻辑在 docs/api/README.md 的文件与图片引用一节有完整说明以下限制对知识搜索接口同样适用需要外链能力直链由存储后端预签名或由APP_EXTERNAL_URL/r/token提供。二者都不可用时例如 local 存储且未设置APP_EXTERNAL_URL引用会保持resource://原样客户端仍可回退到带鉴权的GET /files代理取字节流。直链是限时匿名可读的WeKnora 签发的 grant 有效期为 2 小时MinIO 预签名有效期为 24 小时。任何拿到链接的人在过期前都能读取该文件请勿将直链写入日志或转发给不应看到该文件的一方。同一文件的直链在有效期内会复用重复请求不会反复签发凭证客户端和 CDN 的缓存因此可以命中凭证被吊销或过期后链接立即失效。限定知识库的 API Key 不能使用public这类 Key 会被返回403因为它们本身也被拒绝访问/files代理若拿到匿名直链等于绕过了同一道限制改用默认的handle即可正常调用。优先级规则单次请求的resource_urls参数优先于环境变量RESOURCE_URL_MODEpublic因此部署默认设为public后仍可用?resource_urlshandle单独退回内部引用模式。常见错误与排查建议结合官方错误处理约定docs/api/README.md#错误处理与上述源码校验逻辑可以归纳出该接口最常见的失败场景现象原因处理HTTP 400提示 Query 为空请求体缺少query字段或为空串检查 JSON 体query字段HTTP 400提示至少需要一种检索目标未传knowledge_base_id/knowledge_base_ids/knowledge_ids且无标签作用域补充知识库 ID 或文件 IDHTTP 400resource_urls取值非法传了handle/public之外的值修正为合法枚举值HTTP 403resource_urlspublic被拒当前 API Key 被限定到特定知识库范围改用handle或换用全权限 API Key返回了resource://引用但无法加载存储后端未配置外链能力如 local 存储缺APP_EXTERNAL_URL通过GET /files?file_path引用代理获取字节流结语POST /knowledge-search是 WeKnora 中检索与问答解耦的典型接口它把召回、去重、重排、阈值过滤这一整套检索管线以结构化 JSON 暴露出来让开发者可以独立于对话流程使用检索能力。无论是做检索质量评估、构建下游 RAG 管线还是把命中片段作为证据接入自有系统掌握本文介绍的请求参数、响应字段与底层校验/重排机制都能帮助你正确、高效地使用该接口。更完整的接口 schema 可在启动服务后访问 Swagger UI非 release 模式下http://localhost:8080/swagger/index.html在线查阅与试调。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WeKnora 知识搜索 API 完全指南：从请求参数到检索结果的源码级解析
WeKnora 知识搜索 API 完全指南从请求参数到检索结果的源码级解析【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnoraWeKnora 的POST /api/v1/knowledge-search接口提供了一条纯检索、不经过 LLM 总结的知识搜索通道输入查询文本直接在知识库中召回相关分块chunk返回按相关性排序的检索结果。本文以官方 API 文档 docs/api/knowledge-search.md 为主体结合仓库中该接口的请求结构体、Handler 实现与检索/重排链路源码系统讲解请求参数、返回字段、resource_urls直链机制以及底层的校验与检索原理帮助你把这个接口集成进自己的应用或脚本。接口概览方法路径描述POST/api/v1/knowledge-search在知识库中搜索相关内容不使用 LLM 总结直接返回检索结果该接口属于 WeKnora 的知识搜索分类完整 API 清单见 docs/api/README.md适用于以下典型场景需要把检索结果作为结构化数据用于二次处理例如喂给自定义的提示词模板、构建下游管线需要在发问前先定位证据片段人工确认检索质量需要跨多个知识库或限定到特定文件进行范围化检索。与knowledge-chat等问答接口不同知识搜索不会调用大模型生成答案因此响应延迟更低、返回内容完全可控便于做检索评估与调试。请求参数详解请求体JSON Body字段类型必填说明querystring是搜索查询文本knowledge_base_idstring否单个知识库 ID向后兼容与knowledge_base_ids互斥knowledge_base_idsstring[]否多个知识库 ID 列表跨知识库搜索knowledge_idsstring[]否进一步限定到指定知识文件不传则在整库范围内搜索必须指定knowledge_base_id或knowledge_base_ids中的至少一个。从源码看接口的请求结构体定义在 internal/handler/session/types.go#L72-L80// SearchKnowledgeRequest defines the request structure for searching knowledge without LLM summarization type SearchKnowledgeRequest struct { Query string json:query binding:required // Query text to search for KnowledgeBaseID string json:knowledge_base_id // Single knowledge base ID (for backward compatibility) KnowledgeBaseIDs []string json:knowledge_base_ids // IDs of knowledge bases to search (multi-KB support) KnowledgeIDs []string json:knowledge_ids // IDs of specific knowledge (files) to search TagIDs []string json:tag_ids // Tag IDs for filtering within a single KB MentionedItems []MentionedItemRequest json:mentioned_items // Optional scoped tag mentions }值得注意的是结构体中还存在官方 markdown 文档未展开列出的两个字段从源码注释可以确认其语义tag_idsstring[]在单个知识库内按标签 ID 过滤mentioned_items[]MentionedItemRequest可选的带作用域的标签提及scoped tag mentions用于把检索范围进一步收窄到某些标签上下文。查询参数Query Stringresource_urls取值为handle默认或public。public会把检索结果content/image_info里的resource://引用替换为可加载的 http(s) 链接详见 docs/api/README.md#文件与图片引用resource-与直链。请求示例官方文档给出了三种典型调用这里完整保留并补充说明# 搜索单个知识库 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_base_id: kb-00000001 } # 搜索多个知识库 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_base_ids: [kb-00000001, kb-00000002] } # 搜索指定文件knowledge_ids 与知识库参数配合使用 curl --location http://localhost:8080/api/v1/knowledge-search \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 如何使用知识库, knowledge_ids: [4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5] }三个要点认证所有请求需要在 HTTP 请求头携带X-API-Key获取方式见 docs/api/README.md 的认证机制一节为便于追踪问题官方还建议附带X-Request-ID请求头。基础 URL接口挂在/api/v1前缀之下完整路径为http://localhost:8080/api/v1/knowledge-search。单库与多库互斥语义knowledge_base_id是为旧客户端保留的单数形式。在 Handler 实现中internal/handler/session/qa.go#L809-L823服务端会把knowledge_base_id合并进knowledge_base_ids列表并做去重因此两者同时传入也不会重复检索只是单数形式最终统一按多库逻辑处理。响应格式与字段说明完整响应示例{ data: [ { id: chunk-00000001, content: 知识库是用于存储和检索知识的系统..., knowledge_id: knowledge-00000001, chunk_index: 0, knowledge_title: 知识库使用指南, start_at: 0, end_at: 500, seq: 1, score: 0.95, chunk_type: text, image_info: , metadata: {}, knowledge_filename: guide.pdf, knowledge_source: file } ], success: true }响应字段说明data[]字段类型说明idstring分块 IDcontentstring命中的分块文本knowledge_idstring该分块所属的知识 IDchunk_indexint分块在知识中的序号knowledge_titlestring来源知识标题start_at / end_atint分块在源文档中的字符偏移seqint命中排序号scorenumber相似度rerank 后归一化后的最终得分chunk_typestring分块类型text/image/ ...image_infostring图像分块的额外信息JSON 字符串metadataobject自定义元数据knowledge_filenamestring来源文件名knowledge_sourcestring来源类型file/url/manual几个容易忽略的细节start_at/end_at是分块在源文档中的字符偏移区间可用于在原文中定位命中片段chunk_type为image时image_info会携带图像的额外信息JSON 字符串配合resource://引用或resource_urlspublic直链即可加载图片knowledge_source标识知识的来源形态file上传文件、url网页采集、manual手工录入。请求校验与执行链路源码视角在 Handler 层SearchKnowledge的实现位于 internal/handler/session/qa.go#L781其执行顺序可以归纳为四步每一步都能在源码中找到对应逻辑解析与空校验c.ShouldBindJSON(request)解析请求体随后显式检查Query是否为空为空直接返回 400Query content cannot be empty。解析 resource_urls先解析存储引用表示方式handle/public如果传了非法值或当前凭证不允许public模式会在这里提前拒绝避免浪费后续检索开销——源码注释明确说明这是在检索前解析让拼写错误或被拒绝的作用域不产生代价。向后兼容合并与作用域校验把单数knowledge_base_id合并进knowledge_base_ids对tag_ids/mentioned_items做去重与作用域校验validateUnscopedTagIDs、mergeTagScopesFromRequestIDs。目标合法性校验如果knowledge_base_ids、knowledge_ids、标签作用域全部为空返回 400At least one knowledge_base_id, knowledge_base_ids, knowledge_ids, or scoped tag must be provided随后通过types.AuthorizeTenantAPIKeyKnowledgeTargets校验当前 API Key 是否有权访问这些检索目标。从路由注册看该接口定义在 internal/router/routes_chat.go#L127knowledgeSearch : g.apiKeyGroup(r.Group(/knowledge-search, g.Viewer()), apiKeyRetrieve(apiKeyFullAccess()))其中g.Viewer()表明访问者级别Viewer即可调用apiKeyRetrieve(apiKeyFullAccess())则用于取出并鉴权 API Key——这也意味着限定知识库范围的 API Key 在权限控制上有着更细的约束详见下文注意事项。检索与重排Rerank原理知识搜索返回的score字段标注为rerank 后归一化后的最终得分其背后的重排逻辑在 Agent 侧的检索工具中有完整的对应实现位于 internal/agent/tools/knowledge_search.go召回后先去重deduplicateResults在重排前对多路召回结果做去重降低重排开销多查询合并当存在多个查询子句时取第一个查询作为重排查询或用空格拼接多个查询strings.Join(queries, )重排模型可用时调用rerankResults对召回结果打分重排并按阈值rerankThreshold()过滤重排失败时优雅降级——源码注释明确说明A failed rerank call degrades to the raw retrieval order即直接退回原始检索顺序保证接口可用性重排后二次去重因为重排可能改变分数与顺序代码在重排之后还会再做一次最终去重避免重复项残留MMR 阶段注释中还提到结果会经过 MMRMaximal Marginal Relevance处理兼顾相关性relevance与多样性diversity。也就是说一次知识搜索的完整数据流是多路召回 → 去重 → Rerank 重排可选失败降级→ 阈值过滤 → 最终去重 → 按得分排序输出。score反映的是重排模型归一化后的相关度分数seq则是命中在最终结果中的排序号。关于resource_urlspublic直链的重要注意事项resource_urls查询参数的控制逻辑在 docs/api/README.md 的文件与图片引用一节有完整说明以下限制对知识搜索接口同样适用需要外链能力直链由存储后端预签名或由APP_EXTERNAL_URL/r/token提供。二者都不可用时例如 local 存储且未设置APP_EXTERNAL_URL引用会保持resource://原样客户端仍可回退到带鉴权的GET /files代理取字节流。直链是限时匿名可读的WeKnora 签发的 grant 有效期为 2 小时MinIO 预签名有效期为 24 小时。任何拿到链接的人在过期前都能读取该文件请勿将直链写入日志或转发给不应看到该文件的一方。同一文件的直链在有效期内会复用重复请求不会反复签发凭证客户端和 CDN 的缓存因此可以命中凭证被吊销或过期后链接立即失效。限定知识库的 API Key 不能使用public这类 Key 会被返回403因为它们本身也被拒绝访问/files代理若拿到匿名直链等于绕过了同一道限制改用默认的handle即可正常调用。优先级规则单次请求的resource_urls参数优先于环境变量RESOURCE_URL_MODEpublic因此部署默认设为public后仍可用?resource_urlshandle单独退回内部引用模式。常见错误与排查建议结合官方错误处理约定docs/api/README.md#错误处理与上述源码校验逻辑可以归纳出该接口最常见的失败场景现象原因处理HTTP 400提示 Query 为空请求体缺少query字段或为空串检查 JSON 体query字段HTTP 400提示至少需要一种检索目标未传knowledge_base_id/knowledge_base_ids/knowledge_ids且无标签作用域补充知识库 ID 或文件 IDHTTP 400resource_urls取值非法传了handle/public之外的值修正为合法枚举值HTTP 403resource_urlspublic被拒当前 API Key 被限定到特定知识库范围改用handle或换用全权限 API Key返回了resource://引用但无法加载存储后端未配置外链能力如 local 存储缺APP_EXTERNAL_URL通过GET /files?file_path引用代理获取字节流结语POST /knowledge-search是 WeKnora 中检索与问答解耦的典型接口它把召回、去重、重排、阈值过滤这一整套检索管线以结构化 JSON 暴露出来让开发者可以独立于对话流程使用检索能力。无论是做检索质量评估、构建下游 RAG 管线还是把命中片段作为证据接入自有系统掌握本文介绍的请求参数、响应字段与底层校验/重排机制都能帮助你正确、高效地使用该接口。更完整的接口 schema 可在启动服务后访问 Swagger UI非 release 模式下http://localhost:8080/swagger/index.html在线查阅与试调。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考