企业官网建设流程全解析

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 能帮你做什么

如果你的需求是"把私有文档变成可检索、可追问的接口"，下面这条链路可以直接照着做。

这张截图是 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_multimodel="true"' \ --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；输出是知识库对象。关键参数建议：

最常见的坑：embedding_model_id决定了整个库的向量空间，换模型等于重建库，跨库检索（knowledge_base_ids传多个 ID）也要求它们共享同一个 embedding 模型。

灌数据：一个异步任务加五个状态

输入是 multipart 文件；输出是知识对象，核心是parse_status字段。它的取值链路是：

边界情况：同一个文件再传一次会返回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是references，knowledge_references数组里每条含content（原文片段）、knowledge_title（来源文件）、chunk_index（分块序号）和score。答案正文逐帧以response_type: answer推送，最后一帧done为true。要核对答案出处，拿knowledge_id+chunk_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控制条数，默认 20：

curl --location 'http://localhost:8080/api/v1/messages/your-session-id/load?limit=10' \ --header 'X-API-Key: your-api-key'

第 5 步，处理图片引用。答案或分块里如果出现resource://xxx形式的图片引用，它不能被浏览器直接加载：要么客户端再调GET /files?file_path=<引用>代理拿字节流，要么在请求 URL 上加?resource_urls=public让服务端直接换回限时直链。直链是匿名可读的（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/WeKnora，client/目录即 SDK，cli/目录有同构的命令行实现可参考

【免费下载链接】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