WeKnora 会话、消息与聊天 API 实战指南从创建会话到 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 HTTP API 中“会话Session、消息Message与聊天Chat”部分的完整技术指南。会话是用户私有的对话载体聊天接口通过 SSE 流式返回知识库问答RAG与智能体Agent回答并支持临时附件、追问建议、断线续传、生成文件下载等能力。读完本文你将掌握 WeKnora 会话生命周期的全部接口用法、SSE 流式协议的事件语义、API Key 的chat/retrieve/message_history能力边界以及每条接口背后的源码实现位置。会话模型与权限边界在 WeKnora 中会话Session是用户私有资源handler 内部强制进行归属校验路由层统一要求 Viewer 角色RBAC 开启时也就是说非空间成员即使拿到路由也无法到达 handler。路由注册与 API Key 策略见 internal/router/routes_chat.go/sessions全部路由挂在g.Viewer()之下API Key 需要chatcapability或 full-access消息搜索/messages/search与索引统计需要message_historycapability知识检索/knowledge-search需要retrievecapability。从源码结构看会话相关的接口路由统一收敛在router.go的RegisterSessionRoutes、RegisterChatRoutes、RegisterMessageRoutes三个函数中见 internal/router/router.go#L276-L278而 handler 实现在internal/handler/session/目录下handler.go、qa.go、stream.go、title.go、temporary_document.go以及internal/handler/message.go、internal/handler/message_suggestion.go。一、会话生命周期管理/api/v1/sessions1.1 创建会话POST /api/v1/sessions创建会话只需title与description两个可选字段响应 201 返回完整 Session 对象含id, title, description, tenant_id, user_id, is_pinned, last_request_state, created_at等。curl -X POST $BASE/api/v1/sessions -H X-API-Key: $API_KEY \ -H Content-Type: application/json -d {title:新对话}从源码看会话 handler 依赖一组服务sessionService、messageService、streamManager、knowledgebaseService、customAgentService、temporaryDocuments、memoryService等见 internal/handler/session/handler.go#L18-L50说明会话对象是聊天、Agent、附件、长期记忆等能力共用的状态载体。1.2 会话列表GET /api/v1/sessions列表接口支持分页与多维过滤响应形如{success:true,data:[SessionListItem],total,page,page_size}查询参数类型必填说明page/page_sizeint否分页默认值遵循总览约定page1page_size20keywordstring否标题模糊搜索sourcestring否来源过滤web / embed / api / feishu / wechat / slack / ...agent_idstring否按 Agent 过滤主要针对 IM 渠道产生的会话curl $BASE/api/v1/sessions?page1 -H Authorization: Bearer $TOKEN1.3 会话详情、更新与删除详情GET /api/v1/sessions/:id返回 200{success:true,data:{Session}}。更新PUT /api/v1/sessions/:id请求体为可选的title、description、is_pinned用于重命名、补充描述或置顶。删除DELETE /api/v1/sessions/:id返回 200{success:true,message:Session deleted successfully}。批量删除DELETE /api/v1/sessions/batch请求体{ids:[s-1],delete_all:false}ids与delete_all:true二选一。清空消息DELETE /api/v1/sessions/:id/messages只清空会话内消息不删除会话本身。curl $BASE/api/v1/sessions/s-1 -H Authorization: Bearer $TOKEN curl -X PUT $BASE/api/v1/sessions/s-1 -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {title:重命名} curl -X DELETE $BASE/api/v1/sessions/s-1 -H Authorization: Bearer $TOKEN curl -X DELETE $BASE/api/v1/sessions/batch -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {ids:[s-1,s-2]} curl -X DELETE $BASE/api/v1/sessions/s-1/messages -H Authorization: Bearer $TOKEN1.4 自动生成标题POST /api/v1/sessions/:session_id/generate_title根据上下文消息由模型生成会话标题messages字段为必填binding:required典型用法是前端拿到首轮问答后调用服务端返回data为生成的标题字符串。Handler 位于 internal/handler/session/title.go内部调用sessionService.GenerateTitle完成模型摘要。curl -X POST $BASE/api/v1/sessions/s-1/generate_title -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {messages:[{role:user,content:介绍下产品}]}1.5 停止生成POST /api/v1/sessions/:session_id/stop流式回答还在进行时可传入message_id必填助手消息 ID中止当前生成返回{success:true,message:Generation stopped}。Handler 位于 internal/handler/session/stream.go通过 streamManager 停止对应消息的事件产出。curl -X POST $BASE/api/v1/sessions/s-1/stop -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {message_id:m-1}1.6 置顶 / 取消置顶POST /api/v1/sessions/:session_id/pin置顶DELETE /api/v1/sessions/:id/pin取消置顶均无请求体响应{success:true,is_pinned:true|false}。curl -X POST $BASE/api/v1/sessions/s-1/pin -H Authorization: Bearer $TOKEN curl -X DELETE $BASE/api/v1/sessions/s-1/pin -H Authorization: Bearer $TOKEN1.7 断线续传GET /api/v1/sessions/continue-stream/:session_id这是流式聊天场景的关键兜底能力客户端断线重连后通过查询参数message_id必填要续传的助手消息 ID重放历史事件并以 100ms 轮询持续追加新增量直到流以complete事件终止。响应为text/event-stream事件格式见 API 总览的“流式接口协议”一节website-docs/04-api/01-api-overview.md。curl -N $BASE/api/v1/sessions/continue-stream/s-1?message_idm-1 -H Authorization: Bearer $TOKEN源码实现位于 internal/handler/session/stream.go#L35-L180先校验会话存在并属于当前租户、再通过streamManager.GetEvents从 offset 0 拉取事件流并完整重放若事件中已含complete则直接发送完成事件否则启动time.NewTicker(100 * time.Millisecond)循环轮询新事件客户端断开Context().Done()即退出。注意若该消息在服务端已不存在如 replay buffer 过期会返回 404 而非 5xx客户端不应重试。二、会话附件临时文档/api/v1/sessions/:id/attachments会话级临时文档用于“先上传、后引用”上传接口立即返回文档 ID解析在后台 worker 异步进行。Handler 位于 internal/handler/session/temporary_document.go。2.1 上传附件POST /api/v1/sessions/:session_id/attachmentsmultipart 字段字段类型必填说明filefile是要上传的文件agent_idstring否决定解析引擎 / ASR 模型 / VLM 模型parser_enginestring否指定解析引擎缺省时从 Agent 聊天规则或租户规则解析响应 202{success:true,data:{TemporaryDocument}}其中status取值为uploaded / processing / ready / failed另含resource_ref供后续引用。curl -X POST $BASE/api/v1/sessions/s-1/attachments -H Authorization: Bearer $TOKEN -F filenotes.pdf从源码看internal/handler/session/temporary_document.go#L19-L93上传会做几件值得注意的事用GetOwnedSession做严格属主校验——管理员可以读取某个 API Key 会话但不能给它加附件文件大小受GetMaxFileSizeMB限制超限的请求体通过http.MaxBytesReader直接截断若指定了agent_id还会检查 Agent 的SupportedFileTypes白名单音频扩展名要求AudioUploadEnabled且配置了ASRModelID图片理解caption/OCR使用 Agent 的VLMModelIDOCR 页数上限由AttachmentOCRMaxPages控制未显式传parser_engine或为auto时按“Agent 聊天规则 → 租户规则”的顺序解析实际引擎。2.2 附件列表、详情、预览与删除列表GET /api/v1/sessions/:id/attachments返回[TemporaryDocument]。详情GET /api/v1/sessions/:id/attachments/:attachment_id包含解析状态。预览GET /api/v1/sessions/:id/attachments/:attachment_id/preview返回文件流Content-Disposition: inline|attachmentCache-Control: private。删除DELETE /api/v1/sessions/:id/attachments/:attachment_id返回 204 No Content。curl $BASE/api/v1/sessions/s-1/attachments -H Authorization: Bearer $TOKEN curl $BASE/api/v1/sessions/s-1/attachments/a-1 -H Authorization: Bearer $TOKEN curl $BASE/api/v1/sessions/s-1/attachments/a-1/preview -H Authorization: Bearer $TOKEN -o preview.pdf curl -X DELETE $BASE/api/v1/sessions/s-1/attachments/a-1 -H Authorization: Bearer $TOKEN三、回答建议Suggestions追问建议是一轮回答结束后的“下一步问题”推荐能力Handler 位于 internal/handler/message_suggestion.go。3.1 读取建议GET /api/v1/sessions/:id/messages/:message_id/suggestions返回{success:true,data:{MessageSuggestionSet}}关键字段statusgenerating / ready / suppressed / failedquestions[{id, text, category, source, knowledge_base_ids}]allow_regenerate是否允许强制重新生成。curl $BASE/api/v1/sessions/s-1/messages/m-1/suggestions -H Authorization: Bearer $TOKEN3.2 触发生成POST /api/v1/sessions/:session_id/messages/:message_id/suggestions幂等触发建议生成请求体{regenerate:true}可选用于强制重新生成。就绪返回 200仍在生成中返回 202data为MessageSuggestionSet|null。curl -X POST $BASE/api/v1/sessions/s-1/messages/m-1/suggestions -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {}3.3 上报交互事件POST /api/v1/sessions/:session_id/suggestion-events用于埋点统计建议的曝光与点击字段类型必填说明suggestion_set_idstring是binding:required建议集 IDquestion_idstring否click / regenerate 事件时必填event_typestring是binding:requiredimpression / click / dismiss / regenerate响应 204 No Content。curl -X POST $BASE/api/v1/sessions/s-1/suggestion-events -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {suggestion_set_id:ss-1,event_type:impression}四、聊天与检索核心聊天与检索的 handler 集中在 internal/handler/session/qa.go。API Key 权限聊天类需chat/fullknowledge-search需retrieve/full。4.1 知识库问答POST /api/v1/knowledge-chat/:session_id基于知识库的 LLM 问答SSE 流式返回以complete事件结束。请求体字段KnowledgeQA 与 AgentQA 共用字段类型必填说明querystring是binding:required用户问题knowledge_base_ids[]string否检索的 KB 列表knowledge_ids[]string否限定知识文件agent_enabledbool否是否启用 Agent 模式agent_idstring否自定义 Agent IDweb_search_enabledbool否是否联网搜索summary_model_idstring否总结模型mcp_service_ids[]string否提及的 MCP 服务skill_names[]string否提及的技能tag_ids[]string否标签过滤mentioned_items[]object否提及项type / kb_id / kb_name / service_id / skill_namedisable_titlebool否禁用自动标题生成images[]object否图片database64 /url/captionattachment_uploads[]object否内联附件database64、file_name、file_sizeattachment_ids[]string否已上传的会话附件 IDchannelstring否来源渠道suggestion_attributionobject否点击建议的归因信息响应为 SSE 流event: messagedata: StreamResponse含answer / references / thinking / session_title / error / complete等response_type以complete事件结束。curl -N -X POST $BASE/api/v1/knowledge-chat/s-1 -H X-API-Key: $API_KEY \ -H Content-Type: application/json \ -d {query:退款政策是什么?,knowledge_base_ids:[kb-1]}从源码看internal/handler/session/qa.go#L868-L892KnowledgeQA走parseQARequest统一解析校验后进入executeQAqaModeNormal模式未显式禁用时自动附带标题生成。parseQARequest会校验 session_id 非空、JSON 绑定成功、query非空见 internal/handler/session/qa.go#L124-L150并把请求上下文KB、Agent、MCP、技能、标签、图片、附件、渠道等组装成types.QARequest交给服务层执行。4.2 Agent 问答POST /api/v1/agent-chat/:session_idAgent 模式下的流式问答除普通answer / references外还会产出thinking / tool_call / tool_result / tool_approval_required / mcp_oauth_required等事件用于呈现推理过程、工具调用与审批。请求体与 knowledge-chat 一致。curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {query:分析上季度数据,agent_id:agent-1}源码实现要点internal/handler/session/qa.go#L894-L941Agent 模式是否启用遵循“自定义 Agent 配置优先于请求标志”的规则customAgent.IsAgentMode()request.AgentEnabled若请求声称启用 Agent 模式却无法解析出agent_id对应的 CustomAgent会在写 SSE 头之前直接返回 400agent_id is required when agent mode is enabled避免前端拿到一个注定失败的流。4.3 无会话知识检索POST /api/v1/knowledge-search不依赖会话的同步检索接口非流式对应SearchKnowledge见 internal/handler/session/qa.go#L781字段类型必填说明querystring是binding:required查询knowledge_base_idstring否单 KB兼容旧版knowledge_base_ids[]string否多 KBknowledge_ids[]string否限定文件tag_ids[]string否标签过滤mentioned_items[]object否带 KB 范围的标签提及响应 200{success:true,data:[SearchResult]}SearchResult 含id, content, knowledge_id, knowledge_title, score, chunk_type, knowledge_base_id等。curl -X POST $BASE/api/v1/knowledge-search -H X-API-Key: $API_KEY \ -H Content-Type: application/json -d {query:部署要求,knowledge_base_ids:[kb-1]}五、消息管理/api/v1/messagesHandler 位于 internal/handler/message.go。消息搜索与历史统计需要message_historycapability会话内消息加载与删除需要chatcapability均要求 Viewer。5.1 聊天历史搜索POST /api/v1/messages/search对整个租户的聊天历史做语义/关键词检索字段类型必填说明querystring是binding:required查询modestring否keyword / vector / hybrid默认 hybridlimitint否默认 20session_ids[]string否限定会话响应 200{success:true,data:{total:N,results:[{session_id,message_id,role,content,created_at,score}]}}。curl -X POST $BASE/api/v1/messages/search -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json -d {query:报价}5.2 聊天历史索引统计GET /api/v1/messages/chat-history-stats返回{success:true,data:{indexed_message_count, knowledge_base_size, last_indexed_at, ...}}用于监控历史消息的向量索引状态curl $BASE/api/v1/messages/chat-history-stats -H Authorization: Bearer $TOKEN5.3 加载会话消息GET /api/v1/messages/:session_id/load按时间游标向前翻页加载消息历史查询参数类型必填说明limitint否默认 20before_timestring否RFC3339 / RFC3339Nano 时间戳用于翻页响应 200{success:true,data:[Message]}Message 含id, session_id, role, content, is_completed, images, attachments, agent_steps等。agent_steps字段让客户端可以重放 Agent 的执行步骤。curl $BASE/api/v1/messages/s-1/load?limit20 -H X-API-Key: $API_KEY5.4 删除单条消息DELETE /api/v1/messages/:session_id/:id权限要求 Viewerhandler 额外校验会话归属API Key 需chat/fullcurl -X DELETE $BASE/api/v1/messages/s-1/m-1 -H Authorization: Bearer $TOKEN六、会话生成文件ArtifactsAgent 执行过程中由技能Skill在沙箱中生成的文件会汇总为 Artifact 列表供客户端下载。以下接口要求 ViewerAPI Key 需chat或 full-access并按会话归属校验不存在或不可访问的会话返回 404。方法路径响应GET/api/v1/sessions/:id/artifacts200{success:true,data:[Artifact]}汇总会话全部文件GET/api/v1/sessions/:id/messages/:message_id/artifacts同上仅本条消息的文件GET/api/v1/sessions/:id/messages/:message_id/artifacts/:index/download200 文件流Content-Disposition: attachmentArtifact 字段index、handle可选 resource:// 引用、file_name、file_type、file_size、source_path、mod_time、created_at。响应不会返回底层对象存储 URL字节流只能走 download 接口。需要特别注意索引语义index从 0 开始且必须使用对应消息列表的索引不能拿会话汇总接口的索引直接拼到消息下载地址上非法索引返回 400越界或文件不存在返回 404。curl $BASE/api/v1/sessions/session-1/messages/message-1/artifacts \ -H Authorization: Bearer $TOKEN curl $BASE/api/v1/sessions/session-1/messages/message-1/artifacts/0/download \ -H Authorization: Bearer $TOKEN -o result.pdf从路由注释internal/router/routes_chat.go#L92-L106可知Artifact 列表接口只暴露元数据文件内容通过带鉴权的 download 端点流式返回从而保证“存储 URL 永不出现在网络上”。实现上由service.ArtifactCollector在 Agent 回合结束后从会话沙箱中收集技能生成的文件handler 中通过artifactCollector字段注入沙箱后端不支持收集时可为 nil。七、回答中的图片与文件引用GET /api/v1/sessions/:id/messages/:message_id/files?file_path...是消息级鉴权代理。file_path传入该消息引用的资源句柄或受支持的存储引用客户端应做 URL 编码。后端会依次校验消息访问权资源与消息的绑定关系知识库 / 共享 Agent 的当前访问权。因此任意文件路径不能仅凭会话 ID 访问授权撤销后旧消息里遗留的引用同样会被拒绝。该机制适用于共享 Agent、组织共享知识库的回答图片与消息产物完整说明见 website-docs/03-features/21-file-access.md。关于“拿到的链接形态”API 总览补充了关键约定回答与检索结果中的图片/附件默认以内部句柄resource://handle返回需要再调一次带鉴权的/files代理第三方应用可在请求 URL 上加?resource_urlspublic或部署级环境变量RESOURCE_URL_MODEpublic切换为可直接渲染的限时直链。聊天相关接口knowledge-chat、agent-chat、continue-stream、messages/:id/load、knowledge-search均支持该参数见 website-docs/04-api/01-api-overview.md 的“文件引用形式resource_urls”一节。八、每轮用量Turn Usage聊天消息会持久化每轮用量usageAgent 完成事件则携带turn_usage它聚合了本轮各用途检索重写、总结、思考、回答等的模型调用结果包含prompt_tokens / completion_tokens / total_tokens / cache_*等字段。需要说明的是工具调用本身并不都会产生 Token用量以模型提供商实际返回或后端已采集的记录为准。字段定义与观测方式详见 website-docs/03-features/16-observability.md。九、实现参考路由与 Handler 索引路由注册RegisterSessionRoutes、RegisterChatRoutes、RegisterMessageRoutes定义在 internal/router/routes_chat.go在 internal/router/router.go#L276-L278 挂载到/api/v1分组。会话 handlerinternal/handler/session/handler.go创建/列表/详情/更新/删除/置顶、internal/handler/session/title.go标题生成、internal/handler/session/stream.go停止生成、断线续传、internal/handler/session/temporary_document.go会话附件、internal/handler/session/qa.goknowledge-chat / agent-chat / knowledge-search。消息与建议internal/handler/message.go消息加载/删除/搜索/索引统计、internal/handler/message_suggestion.go建议读取/生成/事件上报。常见调用链路小结一条典型的“知识库问答”调用链路如下POST /api/v1/sessions创建会话拿到session_id可选POST /api/v1/sessions/:session_id/attachments上传临时文档异步解析后拿attachment_idsPOST /api/v1/knowledge-chat/:session_id发起 SSE 流式问答携带query、knowledge_base_ids必要时带上attachment_ids、images、tag_ids客户端持续消费event: message按response_type渲染answer增量与references引用中途断线时用GET /api/v1/sessions/continue-stream/:session_id?message_id...重放 100ms 轮询续传回答结束后用POST /api/v1/sessions/:session_id/generate_title生成标题读取GET .../messages/:message_id/suggestions展示追问建议Agent 模式产出技能文件时用 Artifact 接口按消息索引下载。整套会话/聊天 API 的设计要点可概括为会话归属强制校验保证数据隔离、SSE 统一事件协议让 RAG 与 Agent 共享同一套流式消费逻辑、continue-stream 提供网络抖动下的断线续传兜底、API Key capability 模型chat/retrieve/message_history让受限机器主体也能安全接入对话能力。【免费下载链接】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），仅供参考