SSE 流式协议

适用读者：Widget 开发者、API 调用方、代理运维人员
API 前缀：/apis/api.ai-suite.halo.run/v1alpha1

使用 SSE 的接口

接口	方法	认证	说明
/chat/stream	POST	匿名	访客流式问答
/search/answer	POST	匿名	搜索页 AI 综合回答
/apis/console.api.ai-suite.halo.run/v1alpha1/writing/assist/stream	POST	管理员	编辑器写作辅助
/apis/console.api.ai-suite.halo.run/v1alpha1/chat/debug/stream	POST	管理员	调试问答、Trace 与引用
/apis/console.api.ai-suite.halo.run/v1alpha1/knowledge/reindex/progress	GET	管理员	全量索引进度

公开聊天和搜索使用 fetch 发送 POST JSON，再通过 ReadableStream 解析响应，不使用只能发送 GET 的 EventSource。

访客聊天请求

POST /apis/api.ai-suite.halo.run/v1alpha1/chat/stream
Content-Type: application/json
Accept: text/event-stream

{
  "message": "站内有哪些关于 AI 的文章？",
  "history": [
    { "role": "user", "content": "你好" },
    { "role": "assistant", "content": "你好，有什么可以帮你？" }
  ],
  "reasoningEnabled": true
}

限制：当前消息最多 4000 字符，历史最多 20 项，每项内容最多 4000 字符。

搜索回答请求

POST /apis/api.ai-suite.halo.run/v1alpha1/search/answer
Content-Type: application/json
Accept: text/event-stream

{
  "keyword": "Halo 插件开发"
}

搜索关键词最多 500 字符。

聊天事件顺序

citations

event:citations
data:[{"title":"文章标题","postId":"post-name","url":"/archives/..."}]

引用事件只在存在引用时发送。客户端不能假设第一帧一定是 citations。

structured_result

命中意图路由且 Pipeline 返回站内文章时，访客聊天会在 token 之前发送结构化结果：

event:structured_result
data:{"type":"article-list","variant":"ranking","title":"热门文章","items":[...]}

variant 当前支持 ranking、latest、tag、category 和 recommendation。内置 Widget 会把它渲染为可点击文章卡片；自定义客户端应在不识别该事件时安全忽略，并继续处理后续 token。

卡片中的标题、链接、摘要和发布时间直接来自 Halo 文章数据，不从大模型文本反向解析。

token

data:{"content":"回答片段"}

token 使用 JSON 包装以保留前后空格和换行。客户端应解析 JSON 后拼接 content，不要直接把整个 data: 内容追加到页面。

reasoning_start / reasoning_delta / reasoning_end

开启深度思考且模型返回推理内容时，服务会把结构化 reasoning 字段或文本中的 <think> / <reasoning> 统一转换为：

event:reasoning_start
data:{}

event:reasoning_delta
data:{"content":"推理片段"}

event:reasoning_end
data:{}

推理事件可能出现在普通 token 之前或之间。客户端应把它们放入独立、默认折叠的区域，不能混入最终回答。不支持这些事件的旧客户端可以安全忽略。完整说明见 深度思考与推理过程。

logId

event:logId
data:550e8400-e29b-41d4-a716-446655440000

logId 用于后续点赞、点踩和 Trace 回溯。搜索回答当前不发送 logId。

DONE

data:[DONE]

收到 [DONE] 后结束本轮解析并恢复输入状态。网络关闭不能完全替代 DONE，因为错误路径也会尽量发送友好提示和 DONE。

错误行为

公开 SSE 为了让前端保持统一解析，部分业务错误仍可能以 HTTP 200 返回，并在 token 中发送友好错误消息，随后发送 [DONE]。

data:{"content":"AI 搜索暂不可用"}

data:[DONE]

调用方需要同时处理：

• 非 2xx HTTP 状态。
• SSE 中的错误文本或 event:error。
• 连接提前关闭。
• 长时间没有数据的超时。
• 正常 [DONE]。

客户端解析状态机

curl 验证

curl -N -X POST \
  'http://127.0.0.1:8090/apis/api.ai-suite.halo.run/v1alpha1/chat/stream' \
  -H 'Content-Type: application/json' \
  --data '{"message":"介绍一下站内内容","history":[]}'

生产域名和 8090 直连结果的到达节奏不同，通常意味着代理缓冲。配置方法见 生产部署。

反馈接口

聊天完成后可使用 logId 提交反馈：

POST /apis/api.ai-suite.halo.run/v1alpha1/chat/feedback?logId=...&type=like&comment=...

反馈接口只接受 POST 请求。

完整路由见 API 总览、Public API 和 Console API。