WeKnora API 实战5 步搭好你的语义检索问答服务【免费下载链接】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你手头有 200 份产品手册客服每天被问同一批参数。你想把文档喂给模型但又不想每次都手动粘贴。WeKnora 提供一套 REST API让你把文档灌进知识库后用几次调用就能跑通语义检索与带引用的智能问答——不需要自己写向量库也不需要自己拼提示词。30 秒速览这套 API 能帮你做什么你要做的事对应端点一句话说明创建空间并发放 KeyPOST /tenants/:id/api-keysKey 代表完整 API 访问权限建库并配置分块策略POST /knowledge-bases指定chunking_config和模型 ID上传文档自动解析向量化POST /knowledge-bases/:id/knowledge/filePDF、Word、网页、Markdown 都支持混合检索向量 关键词POST /knowledge-bases/:id/hybrid-search不经过 LLM直接返回分块和得分流式问答带引用来源POST /knowledge-chat/:session_idSSE 推送先给引用再吐答案拉取会话历史GET /messages/:session_id/load按limit分页回看对话如果你的需求是把私有文档变成可检索、可追问的接口下面这条链路可以直接照着做。这张截图是 Web 端的知识库列表你用 API 创建的库和这里的库是同一份数据配置可以互相对照。拿到第一个回答最小可运行路径整条链路只有三步拿 Key → 建库灌数据 → 检索或问答。全文代码统一用curl服务默认跑在http://localhost:8080路径前缀是/api/v1。认证先搞清 Key 从哪来所有请求都在 HTTP 头里带X-API-Key。Key 的获取有两条路在 Web 页面注册后到账户信息页直接复制或者用 Owner 权限调用POST /tenants/:id/api-keys创建带角色的 Key。官方建议每个请求再带一个X-Request-ID值为任意唯一 ID出问题时服务端日志能直接对上号。建库并上传第一份文档下面这段创建一个文档型知识库chunk_size1000 加 20% 重叠是官方示例给的默认组合先按它走别一上来就调参curl --location http://localhost:8080/api/v1/knowledge-bases \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { name: product-handbook, description: 客服手册库, type: document, chunking_config: { chunk_size: 1000, chunk_overlap: 200, separators: [。\n, \n], enable_multimodal: true }, embedding_model_id: your-embedding-model-id }响应里的data.id就是知识库 ID下文记作kb-xxxx后面所有上传和检索都挂在它下面。接着上传文件。注意用--form提交不要再手动加Content-Type: application/json头否则请求体会被错误解析curl --location http://localhost:8080/api/v1/knowledge-bases/kb-xxxx/knowledge/file \ --header X-API-Key: your-api-key \ --form file/path/to/handbook.pdf \ --form enable_multimodeltrue \ --form metadata{\source\:\product_docs\}上传成功不代表能搜到。响应里parse_status是processing时文档还在解析、分块、向量化用GET /api/v1/knowledge/:id轮询等它变成completed再检索。先跑一次混合搜索验证数据问答之前先用检索接口确认数据真的进来了。这一步不花 LLM 的 token也能立刻看出召回质量curl --location --request POST http://localhost:8080/api/v1/knowledge-bases/kb-xxxx/hybrid-search \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { query_text: X8 是否支持热插拔, vector_threshold: 0.5, keyword_threshold: 0.5, match_count: 5 }返回的data[]每条都是一个命中分块content是原文片段knowledge_title是来源文件名score是归一化后的相似度chunk_index告诉你它在文档第几块。看到对的内容排在前排就可以进入问答了。这张图展示了混合检索的完整流程查询先经过重写然后关键词召回和向量召回并行执行两路结果融合后再做重排序最后输出带得分的分块列表。核心工作流拆解一次完整问答都发生了什么建库 → 灌数据 → 检索 → 生成回答 → 回溯引用五个环节各自的输入输出和坑如下。建库分块策略决定检索上限输入是name、chunking_config、模型 ID输出是知识库对象。关键参数建议参数推荐值为什么chunk_size512~1024太大稀释语义太小丢上下文chunk_overlap约为chunk_size的 20%防止关键句正好被切在两块中间separators中文用[。\n, \n]先按句子边界切再按长度兜底enable_multimodal含图表文档设true开启图文多模态解析最常见的坑embedding_model_id决定了整个库的向量空间换模型等于重建库跨库检索knowledge_base_ids传多个 ID也要求它们共享同一个 embedding 模型。灌数据一个异步任务加五个状态输入是 multipart 文件输出是知识对象核心是parse_status字段。它的取值链路是状态含义pending→processing已入队正在解析 / 分块 / 向量化finalizing主解析完成还在跑摘要、问题生成等索引优化completed/failed/cancelled终态failed可看error_messagecancelled可重新触发解析边界情况同一个文件再传一次会返回409并带上已存在知识的引用不是报错是幂等保护文件超过MAX_FILE_SIZE_MB环境变量上限则返回400。检索两个阈值别设成宁缺毋滥vector_threshold和keyword_threshold同时调高比如都 0.8时结果很容易是空数组——这是新手最常撞到的边界。线上建议从 0.5 起步match_count给 5~10先把召回铺开精度交给后面的重排序。如果只想看纯向量或纯关键词的效果用disable_vector_match/disable_keywords_match单关一路做对照。生成回答SSE 流里的事件顺序是固定的会话在新版 API 里只是个对话容器POST /sessions只传title/description检索范围和智能体在每次提问时由knowledge_base_ids和agent_id指定。问答走POST /knowledge-chat/:session_id请求体核心是query、knowledge_base_ids、可选的agent_id。这张截图是 Web 端的问答界面左侧是对话流回答里附带的引用可以展开看到原文分块——API 返回的knowledge_references就是这个列表的数据源。回溯引用每个答案都能指回原文SSE 流的第一帧response_type是referencesknowledge_references数组里每条含content原文片段、knowledge_title来源文件、chunk_index分块序号和score。答案正文逐帧以response_type: answer推送最后一帧done为true。要核对答案出处拿knowledge_idchunk_index去分块接口docs/api/chunk.md就能翻到原始段落。端到端小场景给手册配一个问答接口前面已经建好库、传好文件、确认parse_status为completed剩下的就四步。第 1 步创建会话只给个标题curl --location http://localhost:8080/api/v1/sessions \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data {title: 手册问答}第 2 步发起流式问答。curl -N关闭缓冲回答和引用会边生成边打印curl --location -N http://localhost:8080/api/v1/knowledge-chat/your-session-id \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { query: X8 是否支持热插拔, knowledge_base_ids: [kb-xxxx] }第 3 步你收到的事件流长这样字段已裁剪仅示意结构event: message data: {response_type:references,done:false,knowledge_references:[{content:X8 系列支持热插拔替换模块时无需停服…,knowledge_title:x8-spec.pdf,chunk_index:12,score:0.93}]} event: message data: {response_type:answer,content:支持。X8 采用模块化电源设计热插拔时…,done:false} event: message data: {response_type:answer,content:,done:true}第 4 步需要回看时拉历史消息limit控制条数默认 20curl --location http://localhost:8080/api/v1/messages/your-session-id/load?limit10 \ --header X-API-Key: your-api-key第 5 步处理图片引用。答案或分块里如果出现resource://xxx形式的图片引用它不能被浏览器直接加载要么客户端再调GET /files?file_path引用代理拿字节流要么在请求 URL 上加?resource_urlspublic让服务端直接换回限时直链。直链是匿名可读的WeKnora 签发的 grant 有效期 2 小时别写进日志。到这里你就有一个提问 → 带出处回答的完整接口了。想省掉自建会话和管理逻辑也可以直接用POST /knowledge-search它跨库检索、不生成回答适合你只想拿分块自己拼 UI 的场景。上生产之前几条实战建议限流与重试偶发 5xx 用指数退避重试2s/4s/8s 起步每个请求带X-Request-ID排查时按 ID 在服务端日志里定位而不是靠时间猜。批量上传要控并发上传本身很快瓶颈在解析队列。按 3~5 个文件的并发提交然后统一轮询parse_status比一把全传上去再串行等待更可控。客户端缓存知识库详情、模型列表这类低频变更数据在本地缓存 5~10 分钟问答主链路只留检索和 chat 两个调用。SSE 长连接超时流式回答可能持续几十秒HTTP 客户端的读超时要放大或设为 0官方 Go 客户端默认对流式请求不设超时自研客户端别沿用普通请求的 10 秒上限。轮询异步任务reparse、批量删除、知识库拷贝都返回任务 ID配套有进度查询接口别用sleep 30 秒再试代替轮询。下一步完整接口与参数表docs/api/README.md检索相关细节在 docs/api/knowledge-search.md 和 docs/api/knowledge-base.md官方 Go 客户端与端到端示例client/example.go封装了建库、上传、流式问答的完整回调写法服务启动后访问http://localhost:8080/swagger/index.html可在线试调所有端点仅非 release 模式挂载字段级参数以它为准需要源码时执行git clone https://gitcode.com/GitHub_Trending/we/WeKnoraclient/目录即 SDKcli/目录有同构的命令行实现可参考【免费下载链接】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 实战：5 步搭好你的语义检索问答服务
WeKnora API 实战5 步搭好你的语义检索问答服务【免费下载链接】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你手头有 200 份产品手册客服每天被问同一批参数。你想把文档喂给模型但又不想每次都手动粘贴。WeKnora 提供一套 REST API让你把文档灌进知识库后用几次调用就能跑通语义检索与带引用的智能问答——不需要自己写向量库也不需要自己拼提示词。30 秒速览这套 API 能帮你做什么你要做的事对应端点一句话说明创建空间并发放 KeyPOST /tenants/:id/api-keysKey 代表完整 API 访问权限建库并配置分块策略POST /knowledge-bases指定chunking_config和模型 ID上传文档自动解析向量化POST /knowledge-bases/:id/knowledge/filePDF、Word、网页、Markdown 都支持混合检索向量 关键词POST /knowledge-bases/:id/hybrid-search不经过 LLM直接返回分块和得分流式问答带引用来源POST /knowledge-chat/:session_idSSE 推送先给引用再吐答案拉取会话历史GET /messages/:session_id/load按limit分页回看对话如果你的需求是把私有文档变成可检索、可追问的接口下面这条链路可以直接照着做。这张截图是 Web 端的知识库列表你用 API 创建的库和这里的库是同一份数据配置可以互相对照。拿到第一个回答最小可运行路径整条链路只有三步拿 Key → 建库灌数据 → 检索或问答。全文代码统一用curl服务默认跑在http://localhost:8080路径前缀是/api/v1。认证先搞清 Key 从哪来所有请求都在 HTTP 头里带X-API-Key。Key 的获取有两条路在 Web 页面注册后到账户信息页直接复制或者用 Owner 权限调用POST /tenants/:id/api-keys创建带角色的 Key。官方建议每个请求再带一个X-Request-ID值为任意唯一 ID出问题时服务端日志能直接对上号。建库并上传第一份文档下面这段创建一个文档型知识库chunk_size1000 加 20% 重叠是官方示例给的默认组合先按它走别一上来就调参curl --location http://localhost:8080/api/v1/knowledge-bases \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { name: product-handbook, description: 客服手册库, type: document, chunking_config: { chunk_size: 1000, chunk_overlap: 200, separators: [。\n, \n], enable_multimodal: true }, embedding_model_id: your-embedding-model-id }响应里的data.id就是知识库 ID下文记作kb-xxxx后面所有上传和检索都挂在它下面。接着上传文件。注意用--form提交不要再手动加Content-Type: application/json头否则请求体会被错误解析curl --location http://localhost:8080/api/v1/knowledge-bases/kb-xxxx/knowledge/file \ --header X-API-Key: your-api-key \ --form file/path/to/handbook.pdf \ --form enable_multimodeltrue \ --form metadata{\source\:\product_docs\}上传成功不代表能搜到。响应里parse_status是processing时文档还在解析、分块、向量化用GET /api/v1/knowledge/:id轮询等它变成completed再检索。先跑一次混合搜索验证数据问答之前先用检索接口确认数据真的进来了。这一步不花 LLM 的 token也能立刻看出召回质量curl --location --request POST http://localhost:8080/api/v1/knowledge-bases/kb-xxxx/hybrid-search \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { query_text: X8 是否支持热插拔, vector_threshold: 0.5, keyword_threshold: 0.5, match_count: 5 }返回的data[]每条都是一个命中分块content是原文片段knowledge_title是来源文件名score是归一化后的相似度chunk_index告诉你它在文档第几块。看到对的内容排在前排就可以进入问答了。这张图展示了混合检索的完整流程查询先经过重写然后关键词召回和向量召回并行执行两路结果融合后再做重排序最后输出带得分的分块列表。核心工作流拆解一次完整问答都发生了什么建库 → 灌数据 → 检索 → 生成回答 → 回溯引用五个环节各自的输入输出和坑如下。建库分块策略决定检索上限输入是name、chunking_config、模型 ID输出是知识库对象。关键参数建议参数推荐值为什么chunk_size512~1024太大稀释语义太小丢上下文chunk_overlap约为chunk_size的 20%防止关键句正好被切在两块中间separators中文用[。\n, \n]先按句子边界切再按长度兜底enable_multimodal含图表文档设true开启图文多模态解析最常见的坑embedding_model_id决定了整个库的向量空间换模型等于重建库跨库检索knowledge_base_ids传多个 ID也要求它们共享同一个 embedding 模型。灌数据一个异步任务加五个状态输入是 multipart 文件输出是知识对象核心是parse_status字段。它的取值链路是状态含义pending→processing已入队正在解析 / 分块 / 向量化finalizing主解析完成还在跑摘要、问题生成等索引优化completed/failed/cancelled终态failed可看error_messagecancelled可重新触发解析边界情况同一个文件再传一次会返回409并带上已存在知识的引用不是报错是幂等保护文件超过MAX_FILE_SIZE_MB环境变量上限则返回400。检索两个阈值别设成宁缺毋滥vector_threshold和keyword_threshold同时调高比如都 0.8时结果很容易是空数组——这是新手最常撞到的边界。线上建议从 0.5 起步match_count给 5~10先把召回铺开精度交给后面的重排序。如果只想看纯向量或纯关键词的效果用disable_vector_match/disable_keywords_match单关一路做对照。生成回答SSE 流里的事件顺序是固定的会话在新版 API 里只是个对话容器POST /sessions只传title/description检索范围和智能体在每次提问时由knowledge_base_ids和agent_id指定。问答走POST /knowledge-chat/:session_id请求体核心是query、knowledge_base_ids、可选的agent_id。这张截图是 Web 端的问答界面左侧是对话流回答里附带的引用可以展开看到原文分块——API 返回的knowledge_references就是这个列表的数据源。回溯引用每个答案都能指回原文SSE 流的第一帧response_type是referencesknowledge_references数组里每条含content原文片段、knowledge_title来源文件、chunk_index分块序号和score。答案正文逐帧以response_type: answer推送最后一帧done为true。要核对答案出处拿knowledge_idchunk_index去分块接口docs/api/chunk.md就能翻到原始段落。端到端小场景给手册配一个问答接口前面已经建好库、传好文件、确认parse_status为completed剩下的就四步。第 1 步创建会话只给个标题curl --location http://localhost:8080/api/v1/sessions \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data {title: 手册问答}第 2 步发起流式问答。curl -N关闭缓冲回答和引用会边生成边打印curl --location -N http://localhost:8080/api/v1/knowledge-chat/your-session-id \ --header Content-Type: application/json \ --header X-API-Key: your-api-key \ --data { query: X8 是否支持热插拔, knowledge_base_ids: [kb-xxxx] }第 3 步你收到的事件流长这样字段已裁剪仅示意结构event: message data: {response_type:references,done:false,knowledge_references:[{content:X8 系列支持热插拔替换模块时无需停服…,knowledge_title:x8-spec.pdf,chunk_index:12,score:0.93}]} event: message data: {response_type:answer,content:支持。X8 采用模块化电源设计热插拔时…,done:false} event: message data: {response_type:answer,content:,done:true}第 4 步需要回看时拉历史消息limit控制条数默认 20curl --location http://localhost:8080/api/v1/messages/your-session-id/load?limit10 \ --header X-API-Key: your-api-key第 5 步处理图片引用。答案或分块里如果出现resource://xxx形式的图片引用它不能被浏览器直接加载要么客户端再调GET /files?file_path引用代理拿字节流要么在请求 URL 上加?resource_urlspublic让服务端直接换回限时直链。直链是匿名可读的WeKnora 签发的 grant 有效期 2 小时别写进日志。到这里你就有一个提问 → 带出处回答的完整接口了。想省掉自建会话和管理逻辑也可以直接用POST /knowledge-search它跨库检索、不生成回答适合你只想拿分块自己拼 UI 的场景。上生产之前几条实战建议限流与重试偶发 5xx 用指数退避重试2s/4s/8s 起步每个请求带X-Request-ID排查时按 ID 在服务端日志里定位而不是靠时间猜。批量上传要控并发上传本身很快瓶颈在解析队列。按 3~5 个文件的并发提交然后统一轮询parse_status比一把全传上去再串行等待更可控。客户端缓存知识库详情、模型列表这类低频变更数据在本地缓存 5~10 分钟问答主链路只留检索和 chat 两个调用。SSE 长连接超时流式回答可能持续几十秒HTTP 客户端的读超时要放大或设为 0官方 Go 客户端默认对流式请求不设超时自研客户端别沿用普通请求的 10 秒上限。轮询异步任务reparse、批量删除、知识库拷贝都返回任务 ID配套有进度查询接口别用sleep 30 秒再试代替轮询。下一步完整接口与参数表docs/api/README.md检索相关细节在 docs/api/knowledge-search.md 和 docs/api/knowledge-base.md官方 Go 客户端与端到端示例client/example.go封装了建库、上传、流式问答的完整回调写法服务启动后访问http://localhost:8080/swagger/index.html可在线试调所有端点仅非 release 模式挂载字段级参数以它为准需要源码时执行git clone https://gitcode.com/GitHub_Trending/we/WeKnoraclient/目录即 SDKcli/目录有同构的命令行实现可参考【免费下载链接】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），仅供参考