MiniMax Provider¶

1. 定位¶

MiniMax 是 Flyto 的高性价比选择,M2.7 模型提供极强的推理能力.优势: - M2.7 高性能低价格 - 三种 API 模式兼容不同生态 - 原生支持 Extended Thinking - Prompt Caching 支持

2. 支持的模型¶

数据来源:core/pkg/providers/minimax/provider.go 静态表(2026-04,结合 capability-probe 实测).

模型	Context Window	Max Output	Input $/1M	Output $/1M	Thinking	Vision	Caching	备注
MiniMax-M2.7	205K	16K	$0.30	$1.20	✓	✓	✓(≥1024t)	最强推理
MiniMax-M2.7-highspeed	205K	16K	$0.30	$1.20	✓	✓	✓(≥1024t)	M2.7 快速变体(实测能力同 M2.7)
MiniMax-M2.5	200K	16K	$0.118	$0.95	✓	✓	✓	高性价比
MiniMax-M2.1	200K	16K	$0.27	$0.95	✓	✗	✓	思考模式
MiniMax-M2	200K	16K	$0.255	$1.00	✗	✗	✓	通用
MiniMax-M1	1M	16K	$0.40	$1.76	✗	✗	✗	1M 长上下文

MaxTools = 0(probe @256 未触发上限,2026-04).CachingMinTokens = 1024(M2 系列). 数据交叉验证:core/docs/capabilities-baseline.json(probed 2026-04).

3. 配置示例¶

Native 模式(推荐)¶

import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/minimax"

p := minimax.New(minimax.Config{
    APIKey:         os.Getenv("MINIMAX_API_KEY"),
    Region:         minimax.RegionGlobal,  // api.minimax.io（默认 RegionChina）
    Mode:           minimax.ModeNative,    // /v1/text/chatcompletion_v2
    ThinkingBudget: 8000,
})

注意:Config 没有 EnableCaching 字段--MiniMax M2 系列在 token 数 ≥ 1024 时由模型自动建立缓存,无需配置.

Anthropic 兼容模式¶

p := minimax.New(minimax.Config{
    APIKey:    os.Getenv("MINIMAX_API_KEY"),
    Mode:      minimax.ModeAnthropic,  // Claude 兼容
    ThinkingBudget: 8000,
})

OpenAI 兼容模式¶

p := minimax.New(minimax.Config{
    APIKey:    os.Getenv("MINIMAX_API_KEY"),
    Mode:      minimax.ModeOpenAI,  // GPT 兼容
    Timeout:   60 * time.Second,    // 可选, 见 §3.1
})

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

Config.Timeout 通过 http.Transport.ResponseHeaderTimeout 实现, 约束"从请求发出到收到响应首字节"的时间, 不影响 SSE 流式响应的后续 body 读取.M2.7 Thinking 模式的长思考 + 长回复不受影响.

MiniMax 特有: 双模式 (ModeAnthropic vs ModeNative/ModeOpenAI) 内部使用两个独立的底层 HTTP client, 但从 Config 层面看统一从 Timeout 字段读取.消费者不需要区分模式, 配置一次生效.

场景	Config 字段	行为
默认 (都不设)	`HTTPClient=nil, Timeout=0`	使用 `defaultTimeout=60s`
显式 Timeout	`HTTPClient=nil, Timeout=Xs`	使用 `Xs` (两模式各自应用)
自定义 client	`HTTPClient=&http.Client{...}`	两模式共享, `Timeout` 被忽略

陷阱警告: 不要误用 http.Client.Timeout - 那会砍死 SSE 流.详见 anthropic.md §3.1 完整论证.

4. 认证方式¶

Bearer Token: Authorization: Bearer <API_KEY>

API Key 获取: MiniMax Platform

5. 能力矩阵¶

能力	支持	备注
Streaming	✓	text_delta
Tool Use	✓	probe @256 未触发上限
Extended Thinking	✓(M2.1+,M2 与 M1 除外)	Native/OpenAI 模式:`reasoning`;Anthropic 模式:`thinking.budget_tokens`
Vision	✓(M2.5/M2.7)	M2.1/M2/M1 不支持
Structured Output	✓	strict_json
Prompt Caching	✓(M2 系列,≥1024t)	自动建立,M1 不支持
Batch API	✗	不支持

6. 已知 quirks¶

三种 API 模式¶

模式	端点	Thinking 参数	稳定性
ModeNative(推荐)	`/v1/text/chatcompletion_v2`	`reasoning`	最稳定
ModeOpenAI	`/v1/chat/completions`	`reasoning`	一般
ModeAnthropic	`/anthropic/v1/messages`	`thinking.budget_tokens`	实测偶发不稳定

建议:优先使用 ModeNative.

$ref 双序列化 Bug¶

MiniMax 的 schema 解析有 bug,带 $ref 的参数会双序列化.实现使用 DereferenceSchema + AdaptSchema workaround(core/pkg/providers/minimax/).

探针发现¶

Tool 数量无硬限制(probe 到 256 未触顶)
Streaming 探测遇到 529(服务过载),重试后成功

7. 错误处理¶

状态码	含义	处理建议
401	API Key 无效	检查 Key
403	无权限	检查账户余额
429	速率限制	等待后重试
529	服务过载	等待后重试
400	请求格式错误	检查 JSON payload

8. 成本估算示例¶

MiniMax-M2.7 处理编程任务(2000 input,800 output,80% cache hit):

Input:   400 tokens × $0.3/1M   = $0.00012
Cache:  1600 tokens × $0.3*0.1/1M = $0.00005
Output:  800 tokens × $1.2/1M    = $0.00096
Total:                            ≈ $0.00113

对比 Claude Sonnet 4.6 相同任务(无 cache):

Input:  2000 tokens × $3/1M     = $0.006
Output:  800 tokens × $15/1M     = $0.012
Total:                            ≈ $0.018

MiniMax M2.7 便宜 16 倍.

9. Region 配置¶

p := minimax.New(minimax.Config{
    APIKey: os.Getenv("MINIMAX_API_KEY"),
    Region: minimax.RegionChina,   // api.minimaxi.com（国内）
    // 或
    Region: minimax.RegionGlobal,  // api.minimax.io（海外）
})

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

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

本 provider 的能力决策来自 req.Capabilities(engine 从 ModelRegistry 注入).包内静态表/const 降级为兜底.

本 provider 的决策路径:

路径	helper	兜底策略
`MaxTools` + `Exhaustive`	`resolveMaxTools`	`minimaxMaxTools = 0`(probe 实测 @256 未触顶,兜底跳过)
`SupportsThinking`	`resolveThinkingSupport`	`modelSupportsThinkingFallback` 扫 `minimaxModels` 静态表(M2.7 / M2.5 / M2.1 true,M2 / M1 false)
`SupportsCaching`	不使用	minimax wire 层自动处理 caching,`Config` 无 `EnableCaching` 字段

minimax 最大的架构特化:双端点共用 dispatcher 层决策.minimax 有两条 stream path(streamOpenAI 走 Native/OpenAI 端点,streamAnthropic 走 Anthropic 兼容端点),但 Stream() dispatcher 统一做 resolveMaxTools + detectFeatureWarnings.两条 path 共用同一份 warning--能力是模型级属性,和序列化格式无关,这样避免在两 path 重复做一遍检查.

轻微行为扩展:streamAnthropic 原本无 max_tools 检查,提到 dispatcher 后新版会有.但兜底 (0, false) 不进 check 分支,nil Capabilities 场景零回归;只有 registry 注入 Exhaustive=true 才触发硬拒.

双开关协议(want × can):Config.ThinkingBudget > 0 或 req.NeedsThinking=true 是 want 信号;registry / 静态表是 can 信号.want=true can=false → warning(典型场景:调 M2 但设了 ThinkingBudget=8000).

11. 消费者注意事项(Token Plan + Anthropic 兼容端点)¶

本节面向使用 MiniMax Token Plan Key(MINIMAX_TOKEN_PLAN_KEY)的消费者,特别是 flysafe 这类从早期 hack 用法迁移过来的项目.完整迁移背景参见 docs/architecture/flysafe-migration-note.md.

11.1 Token Plan Key 的特点¶

免费额度按 call 次数限额(不按 token 计费),面向开发者测试 / 小规模试用场景;
必须走 MiniMax 的 Anthropic 兼容端点:https://api.minimaxi.com/anthropic/v1/messages;
鉴权方式是 Authorization: Bearer $KEY,不是 Anthropic 官方的 x-api-key header.

11.2 推荐用法:`minimax.New(ModeAnthropic)`¶

import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/minimax"

p := minimax.New(minimax.Config{
    APIKey:         os.Getenv("MINIMAX_TOKEN_PLAN_KEY"),
    Region:         minimax.RegionChina,   // 默认即 China，可省略
    Mode:           minimax.ModeAnthropic, // 关键：切到 Anthropic 兼容端点
    ThinkingBudget: 8000,                  // 可选，M2.7 / M2.5 / M2.1 支持
})

几个说明:

Mode: ModeAnthropic 时,New 内部自动拼 https://api.minimaxi.com/anthropic + /v1/messages,并 append api.WithBearerAuth()(参见 provider.go:121-130).消费者不需要手写 BaseURL 或 BearerAuth.
minimax.Config 没有 EnableCaching 字段--minimax wire 层自动处理 caching,无需消费者开关.
能力决策走 minimax 静态表(minimaxModels),M2.7-highspeed 的 SupportsThinking=true / CachingMinTokens=1024 能被正确识别.

11.3 警告:不要用 `anthropic.New(BaseURL hack)`¶

早期做法是用 anthropic.New(Config{BaseURL:"https://api.minimaxi.com/anthropic", BearerAuth:true, …}) 把 MiniMax 冒充成 Anthropic.在 data-driven-capabilities RFC(PR1+PR2)落地之后,这种 hack 会触发两个问题:

thinking false-positive warning:anthropic provider 的能力兜底只扫 anthropicModels,查不到 MiniMax-M2.7-highspeed → 返回 SupportsThinking=false → emit 误报 WarningEvent{Code:"feature_unsupported"}.模型实际是支持 thinking 的.
caching 阈值被保守兜底:anthropic 兜底 CachingMinTokens=4096,而 minimax 实际是 1024.system prompt 落在 1024–4096 区间时 silent 失效--不报错,不警告,caching 没打上,账单不省.

完整触发路径,受影响代码行,次选方案(保留 hack + 手动往 ModelRegistry 注入 ModelInfo),以及不要用 anthropic.Config.ModelOverrides(已 verify 不 work)的原因,参见 flysafe-migration-note.md.

11.4 `ModeAnthropic` 构造链与 `anthropic.New()` 对等(2026-04-11 补齐)¶

2026-04-11 起,minimax.New(ModeAnthropic) 的 api.Client 构造链已补齐到与 anthropic.New() 完全对等的 5 个 api.ClientOption(参见 provider.go:122-149):

WithMessagePath("/v1/messages")
WithAPIVersion("2023-06-01")
WithClassifier(&api.AnthropicClassifier{Hinter: &api.DefaultHinter{}})
WithRetryPolicy(retry.NewAnthropicRetryPolicy(retry.AnthropicRetryOpts{}))
WithOverflowHandler(retry.DefaultOverflowHandler())
WithBearerAuth()(必须,token plan key 就是 Bearer)

对比 anthropic.New() 的差异只在故意的两处:endpoint 指向 minimax 的 /anthropic 路径,auth 强制 Bearer(anthropic provider 默认 x-api-key).错误分类,429/529 重试,max_tokens 溢出修正器的行为全部与 anthropic.New() 等同.

历史记录:此前(2026-04-11 之前)这 4 个 option 缺失.完整补齐前后的影响清单参见 flysafe-migration-note.md §8.

如果后续发现 minimax.New(ModeAnthropic) 与 anthropic.New() 还有其他行为差异(除上述两处故意差异),请回 core 提 issue / PR 补齐,不要在消费者侧 workaround--protocol 细节属于 provider 责任边界.

11.5 验证状态¶

截至 2026-04-11,core 维护者已完成三重验证:

代码路径等价性分析:minimax.New(ModeAnthropic) 与 anthropic.New(BaseURL hack) 的 HTTP wire 完全等同,api.ClientOption 链(除故意差异外)对等.
curl 双路实测:非流式 + 流式 SSE 均 HTTP 200 通过,minimax anthropic 兼容端点完整实现 Anthropic 协议.
Go 端到端 integration test:core/pkg/providers/minimax/provider_integration_test.go(//go:build integration tag 隔离),用真实 MINIMAX_TOKEN_PLAN_KEY 走 minimax.New(Mode: ModeAnthropic) → provider.Stream() → 完整消费 channel,断言收到 UsageEvent(provider 层流终止信号,DoneEvent 由 engine 层追加)+ text 包含期望内容 + 零 feature_unsupported warning.跑法:

go test -tags integration -run TestIntegration_ModeAnthropic_TokenPlan \
    ./pkg/providers/minimax/ -v

2026-04-11 实测结果(补齐 robustness options 前后各跑一次):两次均 PASS,text="OKOK",events=map[text:1 text_delta:1 thinking:1 thinking_delta:5 usage:1].

置信度 100%.消费者可以直接切生产,回滚方案是一行 git revert(HTTP wire 等同,零风险).