47 lines
4.0 KiB
Markdown
47 lines
4.0 KiB
Markdown
# 聊天请求管线(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 接口)一起做更合适。
|