OpenAI Provider¶

1. 定位¶

OpenAI 是 Flyto 的生态丰富 Provider,GPT 系列模型在开发者社区广泛使用.优势: - 丰富的模型家族(GPT-4o,GPT-4.1,GPT-5,o1,o3) - 广泛的工具和集成生态 - OpenAI 兼容接口便于移植

2. 支持的模型¶

数据来源:core/pkg/providers/openai/provider.go 静态表(2026-04).

模型	Context Window	Max Output	Input $/1M	Output $/1M	Thinking	备注
gpt-4o	128K	16K	$2.50	$10	✗	主力模型
gpt-4o-mini	128K	16K	$0.15	$0.60	✗	快速任务
gpt-4.1	1M	32K	$2	$8	✗	长上下文旗舰
gpt-5	400K	32K	$1.25	$10	✗	最新旗舰
o1	200K	100K	$15	$60	✓	推理优化
o3	200K	100K	$10	$40	✓	推理优化
o3-mini	200K	100K	$1.10	$4.40	✓	轻量推理

所有模型 MaxTools = 128(OpenAI Chat API 级别上限).

3. 配置示例¶

import (
    "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/flyto"
    "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/openai"
)

p := openai.New(openai.Config{
    APIKey:  os.Getenv("OPENAI_API_KEY"),
    BaseURL: "https://api.openai.com",  // 可覆盖（如 Azure）
    Timeout: 60 * time.Second,           // 可选,ResponseHeaderTimeout (见 §3.1)
    ModelOverrides: []flyto.ModelInfo{
        {
            ID:               "gpt-4o-2025-01-01",
            Provider:         "openai",
            ContextWindow:    128_000,
            MaxOutputTokens:  16_000,
            InputPricePer1M:  2.50,
            OutputPricePer1M: 10.0,
            MaxTools:         128,
        },
    },
})

3.1 Timeout (P1 契约加固, 2026-04-13)¶

Config.Timeout 通过 http.Transport.ResponseHeaderTimeout 实现, 约束"从请求发出到收到响应首字节"的时间, 不影响 SSE 流式响应的后续 body 读取.

场景	Config 字段	行为
默认 (都不设)	`HTTPClient=nil, Timeout=0`	使用 `defaultTimeout=60s`
显式 Timeout	`HTTPClient=nil, Timeout=Xs`	使用 `Xs`
自定义 client	`HTTPClient=&http.Client{...}`	完全交给消费者, `Timeout` 被忽略 (silent)

陷阱警告: 不要误用 http.Client.Timeout - 那是整个请求总时长,包括流式 body 读取,设 60s 会砍死长流式调用.我们统一用 http.Transport.ResponseHeaderTimeout,OpenAI 长推理模型 (o1/o3) 的 2-5 分钟响应照常工作.

详见 docs/providers/anthropic.md §3.1 的完整论证 -- 所有 provider 采用同一策略.

Azure 覆盖示例¶

p := openai.New(openai.Config{
    APIKey:  os.Getenv("AZURE_OPENAI_KEY"),
    BaseURL: "https://xxx.openai.azure.com/v1",
})

4. 认证方式¶

Bearer Token: Authorization: Bearer <API_KEY>

API Key 获取: OpenAI Platform

5. 能力矩阵¶

能力	支持	备注
Streaming	✓	text delta
Tool Use	✓	128 tools max(API 级硬上限)
Extended Thinking	✓(o1/o3 系列)	GPT-4o/4.1/5 不原生支持
Vision	✓	gpt-4o/4.1/5/o1/o3,o3-mini 例外
JSON Mode	✓	`response_format: {type: "json_object"}`
strict_json	✓	`response_format: {type: "json_schema", ...}`,自动裁剪 `allOf/not/if/then/else`
Prompt Caching	✓	OpenAI 自动隐式缓存(implicit),无需 cache_control
Batch API	-	Provider 未单独实现批量端点

6. 已知 quirks¶

CAP-7: Tool 数量上限¶

在发送前检查 tool 数量,超过 128 返回明确错误(而非 API 的模糊 400).

Schema Adaptation¶

OpenAI 的 strict_json 模式(json_schema)对 allOf/not/if/then/else 支持有限,实现会自动裁剪这些约束以避免验证失败.

推理模型¶

OpenAI 的 o1/o3/o3-mini 在静态表中标记 SupportsThinking=true.引擎层不向请求注入 thinking 相关参数(OpenAI 推理模型由 API 自动启用推理,无需配置 budget).

ModelOverrides¶

可用 ModelOverrides 动态添加新模型,无需更新代码.

7. 错误处理¶

状态码	含义	处理建议
401	API Key 无效	检查 Key
403	无权限	检查账户结算
429	速率限制	等待后重试
400 `invalid_format`	JSON 格式错误	检查 response_format

8. 成本估算示例¶

GPT-4o 快速审查(1000 input,300 output):

Input:  1000 tokens × $2.5/1M  = $0.0025
Output:  300 tokens × $10/1M   = $0.003
Total:                          ≈ $0.0055

GPT-4o-mini(更便宜):

Input:  1000 tokens × $0.15/1M = $0.00015
Output:  300 tokens × $0.60/1M = $0.00018
Total:                          ≈ $0.00033

9. 数据驱动能力(Capabilities)¶

参见 docs/architecture/data-driven-capabilities-rfc.md 了解整体机制.PR2.3(2026-04)落地.

本 provider 的能力决策来自 req.Capabilities(engine 从 ModelRegistry 注入).包内 const openaiMaxTools = 128 降级为兜底.

本 provider 的决策路径:

路径	helper	兜底策略
`MaxTools`	`resolveMaxTools`(返回单 `int`)	`openaiMaxTools = 128`(OpenAI API 级硬上限,OpenAPI spec 明确)
`SupportsThinking`	`resolveThinkingSupport`	`modelSupportsThinkingFallback` 扫 `openaiModels` 静态表(o1 / o3 / o3-mini 返回 true)
`SupportsCaching`	不使用	OpenAI 是 implicit(自动)caching,无 `Config.EnableCaching` 开关

openai 相对通用模板的特化:resolveMaxTools 返回单 int 而非 (int, bool)--OpenAI 的 128 是 API 级上限,永远硬拒超限请求(不存在"probe 下界未触顶"的软处理空间).这把"永远 Exhaustive=true"的不变量编码进类型而非注释.registry 注入 MaxTools=256 时会覆盖兜底.

双开关协议(want × can):用户 want thinking(req.NeedsThinking=true)但模型不支持(gpt-4o 等非 o 系列)时,provider emit WarningEvent{Code:"feature_unsupported"}.openai 不主动注入 thinking 参数(o 系列由 API 自动决策),warning 的作用是让"调 gpt-4o 却期望 thinking"的用户看到期望落空.