徐涛
423 lines
15 KiB
Markdown
423 lines
15 KiB
Markdown
# OpenAI Response Provider 自定义请求头支持
|
||
|
||
## 背景
|
||
|
||
OpenAI Responses API 的部分实现（如火山引擎豆包）需要携带特殊的 HTTP 请求头（如 `ark-beta-doubao-app: true`）来启用平台特定功能。当前 `OpenaiResponseProvider` 在 `build_request_builder()` 中只设置了 `Authorization` 头，没有途径注入自定义请求头。
|
||
|
||
原方案只覆盖 OpenAI Response Provider。经讨论后扩展为**三 Provider 统一**方案：OpenAI Chat（`GenericOpenaiProvider`）、OpenAI Response（`OpenaiResponseProvider`）、Anthropic（`AnthropicProvider`）。
|
||
|
||
核心动机：
|
||
|
||
- OpenAI Responses API 的部分实现需要携带特殊 HTTP 请求头来启用平台特定功能
|
||
- 三种基础协议中，自定义头注入能力不一致
|
||
- 统一 API 让调用方用 `set_extra("custom_headers", ...)` 即可，与底层协议无关
|
||
|
||
## 需求
|
||
|
||
### 功能需求
|
||
|
||
双层自定义头机制：
|
||
|
||
- **Provider 级固定头**：`extra_headers: Vec<(String, String)>`，构造时注入，所有请求自动携带。用于该 provider 所有请求都需要的固定标识头（如平台接入标记）
|
||
- **请求级临时头**：`extra.custom_headers: HashMap<String, String>`，通过 `set_extra` 注入。用于特定请求需要覆盖或追加的头
|
||
|
||
### 约束
|
||
|
||
- 不可引入任何平台特定逻辑（火山、豆包等字符串不得出现）
|
||
- 自定义头仅运行时生效，不进入 JSON 序列化的请求体
|
||
- 兼容已有的 extra 逃生舱机制（builtin_tools、text_format 等）
|
||
- agcore 是支持库，不提供运行时敏感头过滤保护（如 Authorization/Cookie），但文档中应说明风险
|
||
- 不修改 `LlmProvider` trait、`ProviderType` 枚举
|
||
- `create_provider()` 工厂函数只传 `Vec::new()` 作为 extra_headers 默认值，不暴露配置能力；调用方如需 Provider 级固定头，直接构造 provider 后链式调用 `.with_extra_headers()`
|
||
|
||
### 用户故事
|
||
|
||
1. 作为集成者，我想对任意 provider 的请求注入自定义 HTTP 头，以启用平台特有功能（请求级）
|
||
2. 作为集成者，我想在 provider 构造时注入固定头，让所有请求自动携带，避免每次重复指定（Provider 级）
|
||
3. 作为维护者，我想三种基础协议使用统一的 API，调用方无需关心底层 provider 类型
|
||
|
||
## 方案设计
|
||
|
||
### 统一设计原则
|
||
|
||
```
|
||
调用方视角（统一 API）：
|
||
request.set_extra("custom_headers", json!({"X-Foo": "bar"}));
|
||
// 不管底层是 OpenAI Chat / OpenAI Response / Anthropic，都能工作
|
||
|
||
构造方视角（Provider 级）：
|
||
OpenaiResponseProvider::from_parts(..., extra_headers).with_extra_headers(...);
|
||
GenericOpenaiProvider::from_parts(..., extra_headers); // 已有
|
||
AnthropicProvider::from_parts(..., extra_headers);
|
||
|
||
头融合顺序（三 provider 一致）：
|
||
认证头 (Authorization / x-api-key) → Provider 级 extra_headers → 请求级 custom_headers
|
||
↑ 后者覆盖前者
|
||
```
|
||
|
||
### 改动一：GenericOpenaiProvider（openai.rs）
|
||
|
||
**① `OpenaiChatRequest` 新增字段**
|
||
|
||
在 `extra_body`（第 147 行）之后：
|
||
|
||
```rust
|
||
/// 请求级别自定义 HTTP 头。运行时注入，不进入 JSON 请求体。
|
||
/// ⚠️ 与 struct 已有的 `extra_headers: Option<Value>`（OpenAI API 自身的 wire 格式字段）
|
||
/// 不同——后者是 OpenAI API 参数，本字段是 reqwest 层的 HTTP 头注入。
|
||
#[serde(skip)]
|
||
pub custom_headers: HashMap<String, String>,
|
||
```
|
||
|
||
`#[serde(skip)]` 确保该字段不会出现在序列化后的 JSON body 中。
|
||
|
||
**② `convert_request()` 从 extra 提取**
|
||
|
||
在 `parallel_tool_calls`（第 559 行）之后：
|
||
|
||
```rust
|
||
let custom_headers: HashMap<String, String> = request
|
||
.get_extra_opt("custom_headers")
|
||
.unwrap_or_default();
|
||
```
|
||
|
||
**③ `build_request_builder()` 签名改具体类型 + 注入逻辑**
|
||
|
||
第 454 行，签名从 `&impl Serialize` 改为 `&OpenaiChatRequest`（两处调用点传入的均为该类型，安全）：
|
||
|
||
```rust
|
||
fn build_request_builder(
|
||
&self,
|
||
url: &str,
|
||
body: &OpenaiChatRequest, // 从 &impl Serialize 改为具体类型
|
||
) -> Result<reqwest::RequestBuilder, LlmError> {
|
||
let mut builder = self
|
||
.http_client
|
||
.post(url)
|
||
.header("Authorization", format!("Bearer {}", self.api_key));
|
||
|
||
// 头融合顺序见上方「统一设计原则」。
|
||
// Provider 级固定头先注入，请求级临时头后注入（后者覆盖前者）。
|
||
|
||
Ok(builder.json(body))
|
||
}
|
||
```
|
||
|
||
两处调用点（`chat_blocking` 第 628 行、`chat_stream_inner` 第 669 行）传入的都是 `&OpenaiChatRequest`，零影响。
|
||
|
||
**④ `with_extra_headers()` builder 方法**
|
||
|
||
```rust
|
||
/// 注入 Provider 级别固定头。返回 self 以支持链式调用。
|
||
pub fn with_extra_headers(mut self, headers: Vec<(String, String)>) -> Self {
|
||
self.extra_headers = headers;
|
||
self
|
||
}
|
||
```
|
||
|
||
### 改动二：OpenaiResponseProvider（openai_response.rs）
|
||
|
||
**① struct 新增 `extra_headers` 字段**
|
||
|
||
第 287 行，`pub struct OpenaiResponseProvider` 增加：
|
||
|
||
```rust
|
||
pub struct OpenaiResponseProvider {
|
||
// ... 已有字段 ...
|
||
extra_headers: Vec<(String, String)>,
|
||
}
|
||
```
|
||
|
||
**② `from_parts()` 新增参数**
|
||
|
||
第 299 行：
|
||
|
||
```rust
|
||
pub(crate) fn from_parts(
|
||
base_url: String,
|
||
api_key: String,
|
||
model: String,
|
||
http_client: Client,
|
||
timeout_secs: u64,
|
||
extra_headers: Vec<(String, String)>, // 新增
|
||
) -> Self { ... }
|
||
```
|
||
|
||
**③ `with_extra_headers()` builder 方法**
|
||
|
||
```rust
|
||
/// 注入 Provider 级别固定头。返回 self 以支持链式调用。
|
||
pub fn with_extra_headers(mut self, headers: Vec<(String, String)>) -> Self {
|
||
self.extra_headers = headers;
|
||
self
|
||
}
|
||
```
|
||
|
||
**④ `OpenaiResponseRequest` 新增字段**
|
||
|
||
第 73 行，`reasoning` 之后：
|
||
|
||
```rust
|
||
/// 请求级别自定义 HTTP 头。序列化时跳过，仅运行时由 build_request_builder 消费。
|
||
/// stream 模式的修改不影响该字段——header 由 convert_request 在请求构造时注入。
|
||
#[serde(skip)]
|
||
pub custom_headers: HashMap<String, String>,
|
||
```
|
||
|
||
`#[serde(skip)]` 确保该字段不会出现在序列化后的 JSON body 中。
|
||
|
||
**⑤ `convert_request()` 从 extra 提取**
|
||
|
||
第 404 行，`reasoning` 之后：
|
||
|
||
```rust
|
||
let custom_headers: HashMap<String, String> = extra
|
||
.get("custom_headers")
|
||
.and_then(|v| serde_json::from_value(v.clone()).ok())
|
||
.unwrap_or_default();
|
||
```
|
||
|
||
> **注意**：OpenaiResponseProvider 的 `convert_request` 在顶部 destructure 了 `request`，因此使用 `extra.get()` 而非 `request.get_extra_opt()`。两者语义一致，均反序列化为 `HashMap<String, String>`，失败时静默降级为空 HashMap。
|
||
|
||
**⑥ `build_request_builder()` 签名 + 注入逻辑**
|
||
|
||
第 319 行，签名从 `&impl Serialize` 改为 `&OpenaiResponseRequest`（两处调用点传入的均为该类型，安全）：
|
||
|
||
```rust
|
||
/// 构造 HTTP POST 请求 builder（含认证头与额外请求头）。
|
||
///
|
||
/// 头融合顺序：Authorization → Provider 级 extra_headers → 请求级 custom_headers
|
||
/// 后者覆盖前者。
|
||
fn build_request_builder(
|
||
&self,
|
||
body: &OpenaiResponseRequest, // 从 &impl Serialize 改为具体类型
|
||
) -> Result<reqwest::RequestBuilder, LlmError> {
|
||
let mut builder = self
|
||
.http_client
|
||
.post(self.endpoint_url())
|
||
.header("Authorization", format!("Bearer {}", self.api_key));
|
||
|
||
for (k, v) in &self.extra_headers {
|
||
builder = builder.header(k.as_str(), v.as_str());
|
||
}
|
||
|
||
for (key, value) in &body.custom_headers {
|
||
builder = builder.header(key.as_str(), value.as_str());
|
||
}
|
||
|
||
Ok(builder.json(body))
|
||
}
|
||
```
|
||
|
||
两处调用点（`chat_blocking` 第 708 行、`chat_stream_inner` 第 741 行）传入的都是 `&OpenaiResponseRequest`，零影响。
|
||
|
||
### 改动三：AnthropicProvider（anthropic.rs）
|
||
|
||
AnthropicProvider 是唯一没有统一 `build_request_builder` 方法的 provider，需要**前置重构**。
|
||
|
||
**① struct 新增 `extra_headers` 字段**
|
||
|
||
第 36 行：
|
||
|
||
```rust
|
||
pub struct AnthropicProvider {
|
||
// ... 已有字段 ...
|
||
extra_headers: Vec<(String, String)>,
|
||
}
|
||
```
|
||
|
||
**② `from_parts()` 新增参数**
|
||
|
||
第 128 行：
|
||
|
||
```rust
|
||
pub(crate) fn from_parts(
|
||
base_url: String,
|
||
api_key: String,
|
||
model: String,
|
||
http_client: Client,
|
||
timeout_secs: u64,
|
||
extra_headers: Vec<(String, String)>, // 新增
|
||
) -> Self { ... }
|
||
```
|
||
|
||
**③ `with_extra_headers()` builder 方法**
|
||
|
||
```rust
|
||
pub fn with_extra_headers(mut self, headers: Vec<(String, String)>) -> Self {
|
||
self.extra_headers = headers;
|
||
self
|
||
}
|
||
```
|
||
|
||
**④ `AnthropicRequestBody` 新增字段**
|
||
|
||
第 450 行，`stream` 之后：
|
||
|
||
```rust
|
||
struct AnthropicRequestBody {
|
||
model: String,
|
||
max_tokens: u32,
|
||
// ... 已有字段 ...
|
||
/// 请求级别自定义 HTTP 头。运行时注入，不进入 JSON 请求体。
|
||
#[serde(skip)]
|
||
custom_headers: HashMap<String, String>,
|
||
}
|
||
```
|
||
|
||
`#[serde(skip)]` 确保该字段不会出现在序列化后的 JSON body 中。
|
||
|
||
**⑤ `build_request_body()` 从 extra 提取**
|
||
|
||
```rust
|
||
let custom_headers: HashMap<String, String> = request
|
||
.get_extra_opt("custom_headers")
|
||
.unwrap_or_default();
|
||
```
|
||
|
||
**⑥ 提取 `build_request_builder()` 统一方法（前置重构）**
|
||
|
||
```rust
|
||
/// 构造 HTTP POST 请求 builder（含认证头 + 自定义头）。
|
||
/// 认证头（x-api-key / anthropic-version）已由 Client 的 default_headers 提供。
|
||
fn build_request_builder(
|
||
&self,
|
||
body: &AnthropicRequestBody,
|
||
) -> Result<reqwest::RequestBuilder, LlmError> {
|
||
let url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
|
||
let mut builder = self.http_client.post(&url).json(body);
|
||
|
||
for (k, v) in &self.extra_headers {
|
||
builder = builder.header(k.as_str(), v.as_str());
|
||
}
|
||
|
||
for (key, value) in &body.custom_headers {
|
||
builder = builder.header(key.as_str(), value.as_str());
|
||
}
|
||
|
||
Ok(builder)
|
||
}
|
||
```
|
||
|
||
**⑦ 改造 `chat_blocking()` 和 `chat_stream_inner()`**
|
||
|
||
改造前（`chat_blocking`，第 263-269 行）：
|
||
|
||
```rust
|
||
let response = self
|
||
.http_client
|
||
.post(&url)
|
||
.json(&body)
|
||
.send()
|
||
.await
|
||
.map_err(|e| self.map_reqwest_error(e))?;
|
||
```
|
||
|
||
改造后：
|
||
|
||
```rust
|
||
let response = self
|
||
.build_request_builder(&body)?
|
||
.send()
|
||
.await
|
||
.map_err(|e| self.map_reqwest_error(e))?;
|
||
```
|
||
|
||
`chat_stream_inner`（第 298-304 行）同理。
|
||
|
||
### 改动四：create_provider()（provider.rs）
|
||
|
||
依据约束「`create_provider()` 工厂函数不暴露配置能力」，三处分支适配 `from_parts` 的新签名时全部传 `Vec::new()`：
|
||
|
||
```rust
|
||
// OpenaiResponse（第 199-207 行）
|
||
openai_response::OpenaiResponseProvider::from_parts(
|
||
config.base_url, config.api_key, config.model,
|
||
client, config.timeout_secs,
|
||
Vec::new(), // extra_headers 默认空
|
||
)
|
||
|
||
// Anthropic（第 215-221 行）
|
||
anthropic::AnthropicProvider::from_parts(
|
||
config.base_url, config.api_key, config.model,
|
||
client, config.timeout_secs,
|
||
Vec::new(), // extra_headers 默认空
|
||
)
|
||
|
||
// OpenAI Chat（第 185-194 行）— 已有 Vec::new()，无需改动
|
||
```
|
||
|
||
### 调用方式
|
||
|
||
**请求级临时头**（统一 API，三 provider 通用）：
|
||
|
||
```rust
|
||
request.set_extra("custom_headers", serde_json::json!({
|
||
"ark-beta-doubao-app": "true"
|
||
}));
|
||
```
|
||
|
||
**Provider 级固定头**（构造时注入）：
|
||
|
||
```rust
|
||
let provider = OpenaiResponseProvider::from_parts(...)
|
||
.with_extra_headers(vec![
|
||
("ark-beta-doubao-app".into(), "true".into()),
|
||
]);
|
||
```
|
||
|
||
## 风险评估
|
||
|
||
### 风险点与缓解措施
|
||
|
||
| 风险 | 等级 | 缓解措施 |
|
||
|------|------|---------|
|
||
| 用户通过 `custom_headers` 覆盖 `Authorization` 等认证头 | 中 | 文档说明：自定义头按遍历顺序注入，同 key 后注入覆盖前注入。agcore 作为支持库不做运行时拦截 |
|
||
| `serde_json::from_value` 类型错误静默降级为空 HashMap | 低 | 与已有 extra 字段（builtin_tools、text_format）一致的模式，保持行为统一。类型错误时请求正常发出，只是不携带自定义头 |
|
||
| HashMap 迭代顺序不确定影响测试确定性 | 低 | HTTP 协议不要求 header 顺序，wiremock 按名匹配。无需特殊处理 |
|
||
| AnthropicProvider 前置重构引入回归 | 低 | 提取 `build_request_builder` 是纯重构，现有测试覆盖其请求构造行为。重构后运行现有测试套件即可验证 |
|
||
| `build_request_builder` 签名从泛型改为具体类型 | 低 | 已确认两处调用点（chat_blocking / chat_stream_inner）传入的均为具体类型，零影响 |
|
||
| AnthropicProvider 的 `default_headers`（x-api-key / anthropic-version）与 `extra_headers` 同名头合并行为取决于 reqwest 实现 | 低 | 明确约定 Provider 级固定头不应意图覆盖认证头；`build_request_builder` 的 doc comment 中标注认证头来源 |
|
||
|
||
### 设计取舍记录
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| Provider 级 vs 请求级 | 双层都支持 | 满足固定头和临时头两种场景 |
|
||
| `create_provider` 是否暴露 extra_headers | 不暴露，只传 `Vec::new()` | 保持工厂函数签名简洁，固定头通过 builder 方法注入 |
|
||
| 敏感头保护 | 不做运行时拦截，文档说明 | agcore 是支持库，不替调用方做保护 |
|
||
| `OpenaiChatRequest.custom_headers` 命名 | 用 `custom_headers` 而非 `extra_headers` | 避免与已有的 `extra_headers: Option<Value>`（OpenAI API wire 字段）混淆 |
|
||
|
||
## 验证标准
|
||
|
||
### 单元测试（每 provider 4 个）
|
||
|
||
| 测试 | 验证点 |
|
||
|------|--------|
|
||
| `*_custom_headers_from_extra` | `convert_request` / `build_request_body` 能从 extra 提取 `custom_headers` |
|
||
| `*_custom_headers_skipped_in_json` | `#[serde(skip)]` 确保 custom_headers 不进入序列化 JSON body |
|
||
| `*_custom_headers_invalid_type_fallback` | 传入错误类型（如字符串而非对象）时静默降级为空 HashMap |
|
||
| `*_extra_headers_from_constructor` | 验证 `from_parts` / `new_with_name_and_headers` 传入的 `extra_headers` 在 `build_request_builder` 中被正确注入到 HTTP 请求头 |
|
||
|
||
### 集成测试（每 provider 4 个，wiremock）
|
||
|
||
| 测试 | 验证点 |
|
||
|------|--------|
|
||
| `*_custom_headers_are_sent` | mock 匹配器验证 HTTP 请求确实携带自定义头 |
|
||
| `*_provider_level_headers_are_sent` | 验证 Provider 级固定头（通过 `with_extra_headers` 注入）确实出现在 HTTP 请求中 |
|
||
| `*_custom_headers_override_provider_headers` | 当 Provider 级和请求级设置了相同 key 但不同值时，最终 HTTP 请求携带的是请求级的值 |
|
||
| `*_custom_headers_can_override_auth_header` | 注入含 `Authorization` 同 key 的 `custom_headers`，验证最终认证头值被覆盖（使行为可见、可预测，与文档风险说明一致） |
|
||
|
||
### 回归验证
|
||
|
||
1. 运行 `cargo test --features full` 确保所有现有测试通过
|
||
2. `cargo clippy --features full` 无新警告
|
||
3. `cargo fmt --check` 格式一致
|
||
|
||
## 不涉及的改动
|
||
|
||
- 不新增 Feature gate
|
||
- 不修改 `LlmProvider` trait
|
||
- 不修改 `ProviderType` 枚举
|
||
- 不新增任何平台相关代码
|