WeKnora 聊天功能 API 实战指南：知识库问答、Agent 智能问答与 SSE 流式响应

WeKnora 聊天功能 API 实战指南：知识库问答、Agent 智能问答与 SSE 流式响应

【免费下载链接】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 的聊天功能 API 展开，系统讲解基于知识库的 RAG 问答（/knowledge-chat）、基于 Agent 的智能问答（/agent-chat）、知识搜索（/knowledge-search）与回答后推荐问题（suggestions）四个核心接口的请求参数、SSE 流式响应格式与实战调用方法。读完本文，你将能够直接使用curl或任意 HTTP 客户端接入 WeKnora 的对话能力，理解resource_urls直链参数、mentioned_items@提及结构与推荐问题归属校验机制，并能结合源码定位每个接口的底层执行路径。

1. 接口总览

聊天类接口均挂载在基础 URL/api/v1下，使用X-API-Key请求头完成身份认证。下表是聊天功能涉及的完整端点清单：

从源码路由注册看（internal/router/routes_chat.go），前三个接口由session.Handler提供实现：/knowledge-chat与/agent-chat需要chat能力（API Key 具备聊天权限），/knowledge-search需要retrieve检索能力；三个建议相关端点则由独立的MessageSuggestionHandler提供。此外，同一文件还注册了GET /sessions/continue-stream/:session_id，用于客户端断线后重新接入正在进行的流式响应。

2. 认证、错误处理与调试建议

所有请求都需要在 HTTP 头携带 API Key：

X-API-Key: your_api_key

建议同时添加X-Request-ID便于问题追踪与日志关联：

X-Request-ID: unique_request_id

API Key 在 Web 页面完成账户注册后，从账户信息页面获取，它代表账户身份并拥有完整的 API 访问权限，请妥善保管。

错误响应统一采用如下 JSON 结构，并以标准 HTTP 状态码表达请求状态：

{ "success": false, "error": { "code": "错误代码", "message": "错误信息", "details": "错误详情" } }

启动服务后，可访问http://localhost:8080/swagger/index.html查看随代码自动更新的 OpenAPI/Swagger 文档（仅非 release 模式挂载），它是最权威的接口 schema 参考。

3.resource_urls查询参数：handle与public直链

聊天类接口都支持查询参数resource_urls，决定响应中图片、图表、附件引用的表现形式：

• 默认handle模式下，响应里的资源以内部引用resource://<handle>返回（如示意图），浏览器不能直接加载，客户端需要调用带鉴权的GET /files?file_path=<引用>代理获取字节流；
• public模式下服务端返回可直接加载的 http(s) 直链，适合将 WeKnora 集成进自有 App 的场景；
• 该参数同样适用于/agent-chat/:session_id、/knowledge-search、/knowledge-bases/:id/hybrid-search与/sessions/continue-stream/:session_id；
• 传其它值返回400。

直链由存储后端预签名（MinIO 预签名 24 小时）或由APP_EXTERNAL_URL+/r/<token>签发（WeKnora grant 2 小时），两者都不可用时（如 local 存储且未设APP_EXTERNAL_URL），引用保持resource://原样。需要注意：直链是限时匿名可读的，请勿写入日志或转发给无关人员；限定知识库的 API Key 不能使用public（返回403）；嵌入式 embed 渠道强制使用handle。完整注意事项可参阅 文件与图片引用（resource:// 与直链）。

从源码看，该参数在 SSE 流启动前就被解析（internal/handler/session/qa.go），一旦非法值可以在写流前以 400 报告；流式回答中跨 chunk 被截断的引用会先缓冲再改写，客户端拿到的始终是完整链接。

4. POST/knowledge-chat/:session_id：基于知识库的 RAG 问答

基于知识库的 RAG 问答，支持 SSE 流式响应，适用于"给定知识库、给出有引用依据的回答"场景。

4.1 请求参数

其中mentioned_items结构为：

images结构为：

4.2 请求示例

curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ "query": "彗尾的形状", "knowledge_base_ids": ["kb-00000001"], "agent_id": "builtin-quick-answer" }'

4.3 SSE 流式响应

响应为服务器端事件流（Server-Sent Events，Content-Type: text/event-stream）。每帧由event与data组成，data为 JSON 对象，核心字段包括id（请求/消息 ID）、response_type、content、done、knowledge_references。

event: message data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"references","content":"","done":false,"knowledge_references":[{"id":"c8347bef-...","content":"彗星xxx。","knowledge_id":"a6790b93-...","chunk_index":0,"knowledge_title":"彗星.txt","score":4.04,"match_type":3,"chunk_type":"text","knowledge_filename":"彗星.txt"}]} event: message data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"彗尾的形状主要表现为...","done":false,"knowledge_references":null} event: message data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"","done":true,"knowledge_references":null}

流程为：先推送references事件（携带knowledge_references检索引用，包含分块内容、所属知识库/文件 ID、chunk 序号、相关度分数与匹配类型），再流式推送answer内容帧，最后以done: true的answer帧收尾。客户端应缓存knowledge_references并在渲染最终答案时展示引用来源。

4.4 源码执行路径

从 internal/handler/session/qa.go 可以看到，KnowledgeQA处理器依次完成：解析并校验请求（parseQARequest）→ 将mentioned_items与knowledge_base_ids/knowledge_ids合并去重（mergeKnowledgeTargets）→ 执行普通模式问答（executeQA，qaModeNormal）。executeQA内部会异步调用sessionService.KnowledgeQA驱动 RAG pipeline，并将事件总线（EventBus）上的事件翻译为 SSE 帧写入响应；同时根据disable_title决定是否异步生成会话标题（session_title事件）。

值得注意的边界行为（可从源码确认）：

• query为空直接返回400；
• session_id必须属于当前用户，使用严格 owner 作用域校验；
• 图片上传必须由所用 Agent 开启ImageUploadEnabled，否则返回400；
• 客户端提交的图片 URL/Caption 字段会被服务端清空（SSRF 防护），仅由后端在保存后回填。

5. POST/agent-chat/:session_id：基于 Agent 的智能问答

Agent 模式支持更智能的问答，包括工具调用、网络搜索、多知识库检索等能力，并通过 SSE 流将 Agent 的思考、工具调用过程实时推送给客户端。

5.1 请求参数

agent_enabled与agent_id的配合逻辑为：若传了agent_id且该 Agent 配置为 Agent 模式（config.agent_mode），则 Agent 模式优先于请求中的agent_enabled；若agent_enabled=true但无法解析出agent_id，服务端直接返回400（"agent_id is required when agent mode is enabled"），避免生成过程中途失败。agent_id也支持共享 Agent——服务端会先尝试从共享关系中解析（resolveAgent），解析成功后以源空间的租户上下文解析模型、知识库与 MCP 服务，并标记只读共享权限。

5.2 请求示例

curl --location 'http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ "query": "帮我查询今天的天气", "agent_enabled": true, "web_search_enabled": true, "knowledge_base_ids": ["kb-00000001"], "agent_id": "builtin-smart-reasoning", "mentioned_items": [ { "id": "kb-00000001", "name": "天气知识库", "type": "kb", "kb_type": "document" } ] }'

5.3 SSE 流式响应类型

Agent 问答的响应同样是 SSE 流（Content-Type: text/event-stream），但response_type远比普通问答丰富，客户端可根据类型渲染思考卡片、工具调用记录与最终回答：

5.4 响应示例

event: message data: {"id":"req-001","response_type":"thinking","content":"用户想查询天气，我需要使用网络搜索工具...","done":false} event: message data: {"id":"req-001","response_type":"tool_call","content":"","done":false,"data":{"tool_name":"web_search","arguments":{"query":"今天天气"}}} event: message data: {"id":"req-001","response_type":"tool_result","content":"搜索结果：今天晴，气温25°C...","done":false} event: message data: {"id":"req-001","response_type":"answer","content":"根据查询结果，今天天气晴朗，气温约25°C。","done":false} event: message data: {"id":"req-001","response_type":"answer","content":"","done":true}

客户端可按tool_call/tool_result的data.tool_name渲染"正在调用 XX 工具"的进度提示，用thinking帧渲染推理过程卡片。

5.5 源码执行路径

AgentQA（internal/handler/session/qa.go）在parseQARequest基础上额外做了三件事：根据自定义 Agent 的IsAgentMode()决定最终是否走 Agent 引擎；在没有可解析agent_id时提前拒绝；按模式分流到executeQA(qaModeAgent)或退回普通模式。Agent 模式下，Agent 流处理器（internal/handler/session/agent_stream_handler.go）通过独立的 EventBus 订阅引擎事件并翻译为 SSE 帧，同时维护answerSegment列表——非终结轮次流式输出的开场白（如"让我搜索一下…"）会在该轮实际调用工具后被标记为 superseded 并从持久化回答中剔除，避免污染最终答案。

Agent 模式还支持同会话并发保护：一个会话同时只允许一个运行中的轮次（SetLiveRun/rejectIfOtherAgentRunLive），重复发起会返回409（"another turn is already running in this session"）。此外，Agent 轮次完成后会异步持久化agent_steps（思考/工具调用历史），刷新页面后仍能还原推理过程。

6. 回答后推荐问题（suggestions）

回答主消息完成后，服务端会异步生成推荐问题，不阻塞 SSE 的complete/done事件。生成结果按"空间、助手消息、位置、配置快照、语言"持久化并去重——相同配置快照会复用已生成的推荐，避免重复消耗模型额度。

6.1 确保生成或换一批推荐

POST /api/v1/sessions/{session_id}/messages/{message_id}/suggestions Content-Type: application/json {"regenerate": false}

regenerate为false时复用已有推荐（没有才生成），为true时强制重新生成一批。响应状态包括generating、ready、suppressed、failed：

• generating：正在生成，返回 HTTP202；
• ready：生成完成，每个问题都有稳定id；
• suppressed：该消息被压制（如 Agent 配置关闭推荐）；
• failed：生成失败。

6.2 获取已生成的推荐

GET /api/v1/sessions/{session_id}/messages/{message_id}/suggestions

6.3 上报曝光、点击、关闭事件

POST /api/v1/sessions/{session_id}/suggestion-events Content-Type: application/json { "suggestion_set_id": "...", "question_id": "...", "event_type": "click" }

event_type支持exposure（曝光）、click（点击）、close（关闭）等取值。用户点击推荐问题发起新一轮对话时，应在下一次聊天请求中携带suggestion_attribution: {suggestion_set_id, question_id}，服务端会校验归属，防止伪造归属数据。

从源码（internal/handler/message_suggestion.go）可以看到这些端点的具体行为：Ensure对未完成的助手消息返回400；RecordEvent对非法事件类型、缺少question_id（点击事件）等情况返回400，成功则返回204；会话或推荐集合不存在时返回404。

网页嵌入（embed）场景提供同构接口：/api/v1/embed/{channel_id}/sessions/{session_id}/...，继续使用嵌入令牌和X-Embed-Session，便于在外部网页中以匿名访客身份复用同一套推荐交互。

7. POST/knowledge-search：知识库检索

不经过 LLM 总结，直接在知识库中执行检索并返回候选片段，适合构建检索中间层或预取上下文。

请求参数与知识问答共享query、knowledge_base_ids、knowledge_ids、mentioned_items等字段；为兼容旧客户端，还支持单数knowledge_base_id（会自动合并进knowledge_base_ids列表）。请求中必须至少提供knowledge_base_ids、knowledge_ids或带作用域的标签之一，否则返回400。

响应为普通 JSON（Content-Type: application/json），结构为{"success": true, "data": [...]}，其中每个检索结果包含分块内容、所属文件与知识库信息，resource_urls=public时引用会被改写为直链（internal/handler/session/qa.go 中的SearchKnowledge处理器）。

8. 实战接入建议与注意事项

综合源码与文档，接入 WeKnora 聊天 API 时有几个实用要点：

1. SSE 解析：knowledge-chat与agent-chat的每一帧都是event: message+data: {...}，data内的response_type是客户端分派渲染类型的唯一依据；流以done: true的帧收尾，但agent-chat在done后仍可能推送artifacts_pending/complete（Skill 产物上传）帧，客户端不应在收到done后立即关闭流。
2. 资源引用处理：默认handle模式下引用需要二次请求/files代理；若为自有 App 集成且存储后端支持预签名/外部 URL，可统一使用?resource_urls=public。注意嵌入式匿名渠道与限定知识库的 API Key 均不能使用public。
3. 推荐问题闭环：点击推荐后先上报suggestion-events（click），再在下一轮聊天请求中携带suggestion_attribution，两端校验一致才能形成完整数据闭环。
4. 多轮与并发：同一session_id承载多轮上下文；Agent 模式下同会话并发发起会被409拒绝，前端应等待上一轮done后再允许发送。
5. 图片与附件：images传 base64 data URI，且要求所用 Agent 开启图片上传并配置 VLM 模型；文件附件支持 base64 内联（attachment_uploads，单请求最多 5 个、总量不超过 100MB）或预上传会话级文档（attachment_ids），附件解析等待超时默认 60 秒，可通过WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC调整。

更完整的请求 schema、响应字段与试调入口，请以启动后的 Swagger UI（http://localhost:8080/swagger/index.html）为准；相关的知识库、会话、消息与 Agent 管理接口可继续参阅 docs/api/README.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