五分钟跑通 RAG 问答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/WeKnora在内部知识库搜怎么退款返回的却是一篇不相关的工单——问题不在内容缺失而在关键词匹配只比较字符、不理解意图。你需要的是语义检索把问题和文档都转成向量再按意思相近来比对。WeKnora 是一个开源 LLM 知识平台把文档解析、索引、检索、生成封装成一组 REST 接口通过 WeKnora API 即可完成一次 RAG 问答接入。下面先走最短路径跑通链路再拆解检索原理与调优参数最后给出排错清单和工程化建议。从请求视角看一次问答依次经过查询 → 检索 → 生成每一步都对应可独立调用的接口你可以只用到其中某一段。 五分钟跑通第一次问答最短路径只有四步认证、建库、传文件、提问。1. 认证一个请求头就够所有接口挂在/api/v1前缀下请求与响应均为 JSON。身份凭证用 API Key在 Web 端注册后可从账户信息页获取。建议再带上X-Request-ID方便在服务端日志里追踪单次请求。请求头说明X-API-Key身份凭证所有业务接口必传X-Request-ID请求追踪 ID强烈建议Content-Typeapplication/json上传文件时由 multipart 自动生成不要手写2. 三步建好知识库知识库是文档的容器也是检索的范围边界。创建时指定分块策略和嵌入模型——嵌入模型负责把文本转成向量同一库内必须保持一致curl -X POST http://localhost:8080/api/v1/knowledge-bases \ -H X-API-Key: sk-xxxxx -H Content-Type: application/json \ -d { name: 客服资料, chunking_config: { chunk_size: 800, chunk_overlap: 100, separators: [\n\n, \n, 。] }, embedding_model_id: embedding-model-uuid }响应中data.id就是后续步骤要用的知识库 ID。chunk_size太大容易稀释主题太小则上下文残缺800 左右是文档类语料的常见起点。3. 上传第一份文档文件走 multipart 上传服务端会排队执行解析、分块、向量化curl -X POST http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file \ -H X-API-Key: sk-xxxxx \ -F filerefund-policy.pdf上传成功的响应里parse_status为processing。此时还不能提问需轮询GET /knowledge/:id等状态变为completed再进入下一步若是failederror_message里会写明原因。4. 问出第一个问题会话Session是多轮对话的载体先建会话再提问curl -X POST http://localhost:8080/api/v1/sessions \ -H X-API-Key: sk-xxxxx -H Content-Type: application/json \ -d {title: 退款咨询}然后对/knowledge-chat/:session_id发起提问。响应是 SSE 流先推references事件命中的参考分块再逐段推answer直到done为true结束curl -N -X POST http://localhost:8080/api/v1/knowledge-chat/session_id \ -H X-API-Key: sk-xxxxx -H Content-Type: application/json \ -d {query: 退款多久到账, knowledge_base_ids: [kb-00000001]}四步走完你已经拥有了一个可问答的 LLM 知识库。 资源地图一张表看懂核心接口接口按资源分组后其实只有五块完整字段可查 docs/api/README.md。租户与空间空间租户是数据隔离边界不同空间互相不可见方法路径用途POST/tenants创建空间GET/tenants/:id查询空间详情PUT / DELETE/tenants/:id更新 / 删除空间GET/tenants当前用户可见的空间列表知识库与知识方法路径用途POST/knowledge-bases创建知识库GET/knowledge-bases/:id知识库详情含文档/分块计数POST/knowledge-bases/:id/hybrid-search混合检索POST/knowledge-bases/:id/knowledge/file上传文件入库POST/knowledge-bases/:id/knowledge/url从网页或远程文件入库GET/knowledge/:id知识详情轮询解析状态用POST/knowledge/:id/reparse重新解析切换解析引擎后常用会话、问答与消息方法路径用途POST/sessions创建会话POST/knowledge-chat/:session_id知识问答SSEPOST/agent-chat/:session_idAgent 问答支持工具调用与联网搜索POST/sessions/:session_id/stop中止生成GET/messages/:session_id/load拉取会话历史消息⚙️ 核心链路问题如何变成答案混合检索关键词与向量各走一路混合检索Hybrid Search同时跑两路召回向量检索按语义相似度匹配关键词检索按词面精确命中两路候选合并后再统一排序返回。这样意思相近和专有名词、编号、型号都能被捞到。curl -X POST http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search \ -H X-API-Key: sk-xxxxx -H Content-Type: application/json \ -d {query_text: 退款周期, vector_threshold: 0.5, match_count: 10}返回数组每项含content、score、knowledge_title等字段分数低于阈值的候选会被过滤。需要只用单路召回时传disable_vector_match或disable_keywords_match即可。重写、重排序与阈值各管什么影响答案质量的三个旋钮作用各不相同查询重写用户原话往往口语化、缺主语先用 LLM 改写成自包含的检索式问法能明显提高召回质量。重排序Rerank先粗召回一批候选再由重排序模型逐条精算相关性分把最贴切的分块顶到最前。它决定排第一的是不是真正的答案出处。阈值vector_threshold/keyword_threshold取值 0~1是候选分的下限。设得高答案更确定但可能无引用设得低覆盖面广但易混入噪声。这些参数不按请求传递而是由空间级 KV 配置集中管理/tenants/kv/conversation-config、/tenants/kv/retrieval-config改配置即可热生效无需重启。实战走查多轮问答闭环轮次之间如何接力上下文同一个session_id下服务端会自动携带前几轮问答作为上下文第二轮可以直接追问而不必重复主题curl -N -X POST http://localhost:8080/api/v1/agent-chat/session_id \ -H X-API-Key: sk-xxxxx -H Content-Type: application/json \ -d {query: 客户拒绝退货怎么办, knowledge_base_ids: [kb-00000001]}第一轮问退款流程是什么第二轮追问客户拒绝退货怎么办模型能补全省略的主语。需要结合外部信息时在 Agent 模式里加web_search_enabled: true答案就能同时引用知识库与网络结果。中断、续传与查历史三种常见运营动作都有对应接口场景接口中止生成POST /sessions/:session_id/stop断线后恢复流GET /sessions/continue-stream/:session_id拉取历史消息GET /messages/:session_id/load?limit20历史接口返回的每条助手消息都带knowledge_references即当时的参考分块排查答案为什么这样给时直接对照它即可不必重新发起检索。 常见问题与排错错误响应结构与状态码速查失败响应有统一外壳error.code是服务端结构化错误码message给人看details放补充信息{ success: false, error: { code: 1003, message: knowledge base not found, details: } }状态码含义优先检查400参数错误字段名与取值范围、模型/向量存储 ID 有效性401认证失败API Key 是否正确、是否已被吊销403权限不足空间归属Key 是否被限定到指定知识库404资源不存在各级:id是否写错、会话是否已删除409冲突同名同哈希文件重复上传429触发限流降低并发指数退避后重试三个高频坑点上传时别手写 Content-Type。multipart 请求由 curl/客户端自动生成 boundary再手动加application/json会导致请求体解析失败。解析完成前别提问。parse_status未到completed时检索不到内容引用会是空的正确姿势是先轮询知识详情再开放问答入口。SSE 连接别配短超时。流式回答可能持续数十秒官方 Go 客户端对流式请求默认不设超时自己封装 HTTP 调用时同样要保证读超时大于预期回答时长否则答案会写到一半被掐断。工程化优化让调用在规模下稳定缓存与连接复用知识库详情、模型列表这类读多写少的数据客户端加一层带 TTL 的缓存即可显著减少请求量。HTTP 层保持单个客户端实例全程复用——client/client.go 里的http.Client自带连接池避免每次请求新建 TCP 连接。重试与异步重试只针对幂等操作GET 请求、以及 408/429/5xx 用指数退避。上传类 POST 不要盲目重发服务端虽有同文件去重409重复尝试仍浪费带宽。文档解析、知识库拷贝都是异步任务接口先返回任务 ID再用GET /knowledge-bases/copy/progress/:task_id这类进度接口轮询结果不要在请求里同步等待解析完成。收尾从一个问题到一个知识应用小结认证、建库、上传、提问四步构成 RAG 闭环混合检索保证召回面重写、重排序、阈值三个旋钮决定答案精度。把 KV 配置里的检索参数当成可调项做 A/B 验证通常比换模型见效更快。扩展方向与官方入口跑通之后可以沿着三条线扩展Agent 模式接入工具与联网搜索、向量存储与多模型管理、通过 IM 渠道或网页嵌入把问答能力分发到业务端。持续参考的入口接口文档docs/api/README.md随服务启动还可在/swagger/index.html直接试调Go 客户端完整示例client/example.go聊天与 SSE 事件细节docs/api/chat.md【免费下载链接】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），仅供参考