Files
universal-web-api/docs/architecture/chat-pipeline.md
T
2026-11-02 22:54:14 +08:00

47 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 聊天请求管线(R2-2)
## 总览
```
客户端协议 入口(转换请求) 执行(唯一入口) 输出(按协议渲染)
────────────────────────────────────────────────────────────────────────────────────────────────────────────────
OpenAI Chat /v1/chat/completions、/tab/…/v1、/url/…/v1 ─┐
Anthropic /v1/messages、/url/…/v1/messages ─→ 转 ChatRequest ├─→ chat_completions / tab_routes ─→ 浏览器层
OpenAI Responses /v1/responses ─→ 转 ChatRequest ───────────────┘ │ 产出 OpenAI 形状的 SSE chunk
▼
iter_openai_sse_payloads / iter_chat_events(app/core/chat_job.py)
▼
OpenAI:原样透传 │ Anthropic:_anthropic_stream_from_openai │ Responses:_stream_responses_compat
```
- **内部请求**是 `ChatRequest`(OpenAI Chat 形状)加上 `ChatJob`。`ChatJob` 记录协议、模型、是否流式、路由目标和 `X-Request-ID`。
- 协议入口用 `use_chat_job(job_for(...))` 设置 ChatJob;流式响应体在端点函数返回之后才执行,所以要用 `with_chat_job(job, 生成器)` 包起来。
- 执行入口 `request_manager.create_request()` 据此设置 `RequestContext.protocol`,`finish_request()` 再按协议和最终状态记录 `uwapi_chat_requests_total` 与 `uwapi_chat_request_duration_seconds`。
- **内部事件**:执行层的输出统一由 `iter_openai_sse_payloads` 解码(处理增量 UTF-8、CRLF、跨块分帧、注释帧和 `[DONE]`),再由 `events_from_openai_chunk` 拆成类型化的 `ChatEvent`:
| kind | 含义 | 字段 |
|------|------|------|
| `text` | 正文增量 | `text` |
| `reasoning` | 思考过程增量 | `text` |
| `tool_call` | 工具调用增量(OpenAI tool_call 形状) | `data` |
| `media` | 生成的图片、视频等 | `data` |
| `usage` | 用量 | `data` |
| `finish` | 结束原因 | `data["finish_reason"]` |
| `error` | 错误 | `text`、`data` |
## 新增一种客户端协议
1. **请求转换**:把新协议的请求转换成 `ChatRequest`,可参考 `anthropic_routes._anthropic_request_to_openai_payload`。
2. **入口**:新建路由,调用 `chat_api.chat_completions(...)`(或按域名、标签页路由的 `tab_routes` 处理函数),并用 `use_chat_job(job_for("新协议名", ...))` 包住。
- 同时把协议名加入 `app/core/chat_job.PROTOCOLS`。
3. **输出渲染**:流式时用 `iter_chat_events(response.body_iterator)` 消费 `ChatEvent`,渲染成新协议的事件;非流式时把 OpenAI 形状的 JSON 结果转换过去。
- 工具调用、停止序列、媒体、会话续接等能力由执行层统一实现,渲染器只做格式映射。
4. **测试**:
- 在 `tests/test_protocol_conformance.py` 里用该协议的官方 SDK 走一遍流式和非流式;
- 在 `tests/test_chat_job.py::test_each_protocol_is_tagged_and_counted` 里加上该协议。
## 现状与后续
- 现有的 Anthropic 与 Responses 渲染器是两个成熟的状态机(约 1300 行),覆盖工具调用增量、停止序列、媒体、用量、错误映射等细节,已有官方 SDK 一致性测试保护。本次**没有重写**它们,只统一了解码入口;Anthropic 适配器的 `_iter_openai_stream_chunks` 已是共享解码器的别名。
- 下一步可以让浏览器层直接产出 `ChatEvent`,省掉「序列化成 SSE 再解码」这一步;渲染器届时只需改为消费事件。这一步与 R2-1(BrowserDriver 接口)一起做更合适。