配置

初始化优先级

OpenAI::with_options 的读取优先级：

1. 显式 ClientOptions
2. 环境变量
3. 内置默认值

环境变量

• OPENAI_API_KEY（必需，除非显式传入 api_key）
• OPENAI_BASE_URL（默认 https://api.openai.com/v1）
• OPENAI_ORG_ID
• OPENAI_PROJECT_ID
• OPENAI_WEBHOOK_SECRET

ClientOptions 字段

• api_key: Option<String>：API Key。
• organization: Option<String>：组织 ID。
• project: Option<String>：项目 ID。
• webhook_secret: Option<String>：Webhook 密钥，可读取 OPENAI_WEBHOOK_SECRET 环境变量。
• base_url: Option<String>：基础 URL。
• websocket_base_url: Option<String>：WebSocket 基础 URL。
• timeout: Option<Duration>：请求超时，None 表示使用默认超时，默认 Some(600s)。
• max_retries: u32：重试次数，默认 2。
• default_headers: Option<HashMap<String, String>>：客户端默认 headers。
• default_query: Option<HashMap<String, String>>：客户端默认 query。
• _strict_response_validation: bool：严格响应校验，默认 false。

显式配置示例

use std::collections::HashMap;
use std::time::Duration;
use ai_provider_sdk::{ClientOptions, OpenAI};

let mut default_headers = HashMap::new();
default_headers.insert("x-trace-id".to_string(), "demo-trace".to_string());

let client = OpenAI::with_options(ClientOptions {
    api_key: Some("sk-test".to_string()),
    organization: None,
    project: None,
    base_url: Some("https://api.openai.com/v1".to_string()),
    timeout: Some(Duration::from_secs(60)),
    max_retries: 2,
    default_headers: Some(default_headers),
    default_query: None,
})?;

RequestOptions（单次请求覆盖）

• header(key, value)：追加 header。
• query(key, value)：追加 query。
• extra_body(json)：追加/覆盖 body 字段。
• timeout(duration)：覆盖本次请求超时。

示例：

use std::time::Duration;
use ai_provider_sdk::{OpenAI, RequestOptions, ResponseCreateParams};

let client = OpenAI::from_env()?;

let _response = client
    .responses()
    .create_with_options(
        ResponseCreateParams::new("gpt-4.1-mini").input("hello"),
        RequestOptions::new()
            .header("x-trace-id", "trace-123")
            .query("api-version", "test")
            .timeout(Duration::from_secs(30)),
    )
    .await?;

关联阅读

• 安装与使用主线：/guide/overview
• 错误处理：/guide/errors