WeKnora5 步 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 是一个开源 LLM 知识平台把 PDF、Word、网页这些散落文档变成可语义检索、可推理问答的知识资产。读完本文你只用 curl 就能跑通「传文档 → 混合检索 → 流式智能问答」整条链路不需要打开任何 Web 界面。它到底是什么一条完整的 RAG 流水线不是单纯的数据库WeKnora 不是向量数据库的换皮封装也不是一个独立的聊天组件。它是一条完整的 RAG检索增强生成通俗讲就是先翻书再作答流水线文档解析 → 分块 → 向量化 → 混合检索 → LLM 带引用作答。你只管调 REST API解析、检索、排序这些脏活全在服务端。这里先约定两个高频术语混合检索向量召回按语义相似度 关键词召回按字面匹配同时执行再融合专治「换个说法就搜不到」和「专有名词搜不准」两类翻车现场。分块chunk文档被拆成的检索基本单位每次召回的最小颗粒。开工前的最小准备3 项清点克隆仓库并启动服务。前置只需要 Docker 和 Docker Composegit clone https://gitcode.com/GitHub_Trending/we/WeKnora cd WeKnora cp .env.example .env # 按需修改文件内注释已写明每项含义 docker compose up -d拿到 API Key。打开http://localhost注册一个账户进入账户信息页复制 API Key。Key 是后面所有请求的门票丢一次就得重新走一遍流程。验证环境就绪。访问http://localhost:8080/swagger/index.html能看到 Swagger UI 且列出一堆端点说明后端 API 已就绪生产 release 模式下该页面默认关闭本地开发开着。⚠️ 常见坑后端默认端口是8080别把 Web 界面的80当成 API 端口去调。主流程按真实调用顺序走 5 步完整参数细节在 docs/api/ 里下面每步只给最小可运行片段。第 1 步 · 拿到 API Key注册一个账户Key 随响应一起返回拿到 Key后面所有请求才认你。注册端点本身不需要任何鉴权curl -s http://localhost:8080/api/v1/auth/register \ -H Content-Type: application/json \ -d {username:alice,email:aliceexample.com,password:secret123}响应里只关心一处{ success: true, tenant: { id: 1, name: alices workspace, api_key: sk-... } }api_key是唯一的重点把它存进环境变量下面示例统一写作$KEY。⚠️ 常见坑Key 只在这次创建响应里返回一次明文之后查不到另外注册可被环境变量DISABLE_REGISTRATIONtrue整体关掉此时走 Web 界面拿 Key。第 2 步 · 创建知识库必填其实只有一个字段Key 到手下一步是给它一个放文档的容器。POST /knowledge-bases看起来参数很多但只有name必填curl -s http://localhost:8080/api/v1/knowledge-bases \ -H X-API-Key: $KEY -H Content-Type: application/json \ -d { name: weknora-demo, description: demo kb, chunking_config: { chunk_size: 1000, chunk_overlap: 200 } }{ data: { id: b5829e4a-..., name: weknora-demo, knowledge_count: 0 }, success: true }data.id记下后面上传和检索都挂在它下面。embedding_model_id、summary_model_id等模型字段不传就用空间默认配置模型都在 Web 界面里配好即可。⚠️ 常见坑vector_store_id向量存储绑定创建后不可修改不传就走空间级默认存储新手留空即可。第 3 步 · 上传文件灌数据解析是异步的要轮询状态容器有了往里扔一份真实文档。上传走 multipart 表单curl -s http://localhost:8080/api/v1/knowledge-bases/b5829e4a-.../knowledge/file \ -H X-API-Key: $KEY \ -F file./comet.txt{ data: { id: 4c4e7c1a-..., title: comet.txt, parse_status: processing, enable_status: disabled }, success: true }parse_status是本轮的关键字段processing只代表任务入队解析、分块、向量化还在后台跑。轮询知识详情直到completed才算可检索curl -s http://localhost:8080/api/v1/knowledge/4c4e7c1a-... -H X-API-Key: $KEY # 看 data.parse_statuspending → processing → finalizing → completed✅parse_status变成completed后这份文档就参与检索了。⚠️ 常见坑-F会自动带multipart/form-data头千万别再手加Content-Type: application/json请求体会被解析成乱码同一文件重复上传返回 409。第 4 步 · 混合检索不经过 LLM 先验货数据就位先不急着问 LLM用混合检索接口直接看召回质量——这是调试检索效果成本最低的手段curl -s http://localhost:8080/api/v1/knowledge-bases/b5829e4a-.../hybrid-search \ -H X-API-Key: $KEY -H Content-Type: application/json \ -d {query_text: 彗尾的形状, vector_threshold: 0.5, match_count: 5}{ data: [ { content: 彗尾的形状主要表现为...原文段落, knowledge_title: comet.txt, score: 0.95, chunk_index: 0 } ], success: true }content是召回的原文段落score是融合后的得分knowledge_title告诉你命中的是哪个文件——这三项能确认「检索环节本身没出问题」。⚠️ 常见坑结果为空时先降vector_threshold0~1越大过滤越狠再调大match_count两路召回都可以用disable_vector_match/disable_keywords_match单独关掉做对照。第 5 步 · 建会话发起流式问答SSE 事件流怎么拼检索能命中最后交给 LLM 作答。会话接口很简单但注意它的定位变了curl -s http://localhost:8080/api/v1/sessions \ -H X-API-Key: $KEY -H Content-Type: application/json \ -d {title: comet-qa}会话现在只是纯粹的对话容器存标题、描述不再绑定知识库和检索策略——检索范围要在提问时用knowledge_base_ids显式带上。拿到data.id后发起流式问答curl -N http://localhost:8080/api/v1/knowledge-chat/411d6b70-... \ -H X-API-Key: $KEY -H Content-Type: application/json \ -d {query: 彗尾为什么总是背向太阳, knowledge_base_ids: [b5829e4a-...]}-N关闭 curl 缓冲SSE 事件流大致长这样event: message data: {response_type:references,content:,done:false, knowledge_references:[{id:c8347bef-...,content:彗星xxx。, knowledge_title:comet.txt,score:4.04}]} event: message data: {response_type:answer,content:彗尾的形状主要表现为...,done:false} event: message data: {response_type:answer,content:,done:true}拼接规则一句话首个references事件给引用来源answer事件的content逐片拼接done: true收流。用客户端库写的话逻辑相同client/ 里的 Go SDK 已把 SSE 解析封装成回调直接KnowledgeQAStream即可。⚠️ 常见坑忘记在提问请求里带knowledge_base_ids检索会失去范围约束回答质量直接变玄学长回答建议给客户端留出足够的读超时。调优与进阶4 个调节点调两个阈值vector_threshold/keyword_threshold→ 两者独立控制两路召回的过滤力度 → 召回太少就各自下调 0.1 试试宁多勿漏再靠重排兜底。混合检索传knowledge_base_ids跨库召回→ 一次请求同时搜多个知识库省掉客户端做结果合并 → 前提是这些库使用同一 embedding 模型否则召回不到。问答与检索 URL 后加?resource_urlspublic→ 答案里的resource://图片引用直接换成限时 http(s) 直链 → 省掉客户端再调/files代理取图的那次往返适合嵌进自己的 App。轮询parse_status用指数退避1s → 2s → 4s…而不是死循环 → 大文件解析动辄几十秒 → 既省服务端压力也避免把你的脚本挂进无限等待。下一步全量端点与参数docs/api/README.md约 360 个接口的分类索引冲突时以 Swagger UI 为准。想用代码库而不是裸 curlGo 官方客户端在 client/命令行场景可以看 cli/README.md 的weknoraCLI。完整产品文档站website-docs/含架构、特性、客户端接入等章节。数据源连接器飞书、Notion、语雀、RSS和向量存储适配还在持续扩充后续方向见 docs/ROADMAP.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），仅供参考