从零调通 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/WeKnora别让关键词匹配继续答非所问。WeKnora 是开源 LLM 知识平台通过 WeKnora API 提供语义检索与智能问答能力把原始文档变成可查询的 RAG 和自主推理 Agent。这篇文章按你动手的顺序走一遍拿钥匙、搭书架、放资料、混合检索最后让它开口回答顺带聊聊常见坑。第一步拿到你的 API Key先说钥匙从哪来。最省事的路径是网页端注册账号再进账户信息页复制你的 API Key——它代表你的账户身份泄露就等于把整间库的门交给别人务必保管好。如果是纯服务端集成也可以用POST /tenants建空间、POST /tenants/:id/api-keys发一把带角色的 Key角色分 viewer / contributor / admin。接下来是每个请求都要带的头curl http://localhost:8080/api/v1/tenants \ -H X-API-Key: sk-xxxx \ -H X-Request-ID: req-0001请求全部走 JSON本地起服务时基础地址是http://localhost:8080/api/v1。调试阶段很推荐 Swagger UIhttp://localhost:8080/swagger/index.html浏览器里直接试调比翻文档快生产默认关闭。请求失败时先看响应它长这样{ success: false, error: { code: 错误代码, message: 错误信息, details: 错误详情 } }对着error.code和message再叠上状态码定位400 参数写错401 是 Key 没带或失效403 权限不够404 资源不存在500 是服务端的事。调试时把X-Request-ID带上日志里就能串起一次完整链路。第二步搭书架——建知识库知识库就像一间书架你得先告诉它按什么规格把书切卡片、用什么模型理解内容。创建走POST /knowledge-bases只给两个最关键的配置curl http://localhost:8080/api/v1/knowledge-bases \ -H X-API-Key: sk-xxxx \ -H Content-Type: application/json \ -d { name: 客服知识库, chunking_config: { chunk_size: 500, chunk_overlap: 50, separators: [\n\n, \n, . ] }, embedding_model_id: 你的嵌入模型ID, summary_model_id: 你的摘要模型ID }先讲chunk_size和chunk_overlap。把一篇长文拆成一张张卡片这就是分块chunk_size是每张卡片最多装多少字chunk_overlap是相邻卡片重叠多少字。卡片太小一张卡讲不清一件事检索拿到的上下文残缺太大一张卡塞进好几个话题语义被稀释还容易超出模型窗口。重叠那段是保险防止一个完整句子正好卡在两张卡片中间被切开。然后是embedding_model_id也就是嵌入模型。它把文字变成一串向量语义检索全靠它问法和原文用词不同只要意思接近向量距离就近。注意嵌入模型一旦定了别随便换换了向量就全变旧文档得重新解析。至于摘要模型和重排序摘要模型给每张卡片写个小标题或概要重排序模型在召回一堆卡片后给它们重新打分排队把最相关的顶到前面。想让答案更准重排这一环别省。完整字段清单在 docs/api/knowledge-base.md这里不逐个念。第三步放资料——上传与解析书架搭好往里放书。上传文件走POST /knowledge-bases/:id/knowledge/file是 multipart 表单注意别手动加Content-Type: application/json让 curl 用--form自己设curl http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file \ -H X-API-Key: sk-xxxx \ -F file./product.pdf \ -F enable_multimodeltrue响应里有个关键字段parse_status上传后通常是processing。这是个坑刚传完不能立刻检索解析是异步的——文档先被解析、分块、再向量化全走完才变成completed。轮询GET /knowledge/:id盯住parse_statusprocessing还在跑completed才能搜failed就去看error_message。放资料不只有文件。抓网页走POST /knowledge-bases/:id/knowledge/url传个url就行服务端自己判断是抓网页还是下载远程文件想直接写 Markdown 用/knowledge/manual。一个库混着文件、网页、手工内容完全没问题。第四步混合搜索——为什么召回更好在真正让 LLM 回答前先看看它从书架上抽出了哪些卡片。混合搜索走POST /knowledge-bases/:id/hybrid-searchcurl http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search \ -H X-API-Key: sk-xxxx \ -H Content-Type: application/json \ -d { query_text: 退货政策怎么算运费, vector_threshold: 0.5, keyword_threshold: 0.3, match_count: 10 }为什么是混合而不是单路因为两条路各补各的短板。向量路语义擅长意思接近但用词不同——用户问多久能退原文写退款时限也能匹配上关键词路擅长字面必须精确——型号、SKU、报错码这些靠语义反而容易漂。两路各召回一批再融合、重排召回率和准确率都更稳。vector_threshold和keyword_threshold是两个闸门阈值放得越低放过的卡片越宽。match_count控制最多返回几张卡。想只看某几个文件加knowledge_ids想同时搜多个库用knowledge_base_ids。这套双路召回是后面智能问答答案质量的地基。第五步让它开口——会话与流式问答最后让它说话。先开会话——现在会话只是个对话容器POST /sessions传个标题就行curl http://localhost:8080/api/v1/sessions \ -H X-API-Key: sk-xxxx \ -H Content-Type: application/json \ -d { title: 客服对话, description: 退货政策咨询 }多轮上下文靠的就是同一个会话 ID你在这个会话里连续问它就记得前面聊过什么能把那运费呢里的那对上上文。拿到session.id后发问题走POST /knowledge-chat/:session_id返回 SSE 流式响应curl -N http://localhost:8080/api/v1/knowledge-chat/session_id \ -H X-API-Key: sk-xxxx \ -H Content-Type: application/json \ -d { query: 退货政策怎么算运费, knowledge_base_ids: [kb-00000001], agent_id: builtin-quick-answer }注意-N关缓冲不然 SSE 一条条推的内容会攒成一坨。流里先来references答案的参考来源增强可信度再逐段推answer最后done: true收尾。只关心最终文本时把response_type answer的content拼起来即可想要过程展示agent-chat还会推thinking、tool_call等事件。想让答案口感更好调的是智能体配置agent_id指向一个 Custom Agent它在背后决定查询重写把口语问题改写成检索友好的形式、兜底策略没检索到相关卡片时回一句固定话而不是硬编以及前面那堆阈值。改配置不用动会话换个agent_id就行。完整参数见 docs/api/chat.md。收尾常见坑与调优调通之后上线前把这几个坑过一遍。第一别在parse_status还没completed时就去检索会搜不到得等解析走完。第二嵌入模型定了别轻易换换了库里向量就作废旧文档要重解析。第三传文件用--form别再叠一层Content-Type: application/json否则请求体被解析错。第四同一文件重复传会返回 409带着已存在知识的引用别当成报错。性能上几个通用招对 5xx 和偶发网络错做指数退避重试知识库列表、模型这类不常变的信息在客户端缓存少打 API上传和解析本来就异步别在主线程里死等轮询状态即可HTTP 连接池复用 TCP 连接省掉反复建连的开销。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考