minimax

MiniMax M 系列生产接入

兼容 OpenAI 的聊天补全端点：https://api.minimax.io/v1，使用 M2.7-highspeed 推理模型（截至 2026-04-29 为高端套餐）。看起来像 OpenAI，但会静默丢弃 6 个 OpenAI 参数，并在 content 中暴露 <think> 推理轨迹。除聊天补全外，该 API 是 MiniMax 原生 API（URL、请求体格式和错误封装均不同——返回 HTTP 200 + base_resp.status_code，而非 HTTP 4xx）。

该模型本身是适用于金融／量化工作的出色定性评判者、理论讲解者和工具编排者，但无法对现实规模的数据进行原始数学运算（推理预算会耗尽），并会在输入不确定时编造看似合理的细节（已有 6 个记录在案的实例）。用于生产时，应搭配 Python 进行数学运算、搭配沙箱验证器检查代码，并使用确定性检测器进行模式识别。

自我演进技能：此技能会在使用过程中持续改进。如果指令有误、参数发生漂移，或需要使用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。事实来源活动档案：~/own/amonic/minimax/（只读参考资料；请勿从此技能中修改）。

🆕 MiniMax-M3 已上线（2026-06-01）。 本文件介绍 M2.7。关于 M3——原生视觉能力、 reasoning_split 可提供干净输出、接受 response_format、约 1M 输入上限（可靠检索上限 ≤ 约 256K）／524K 输出上限、 n=1，以及文档与实际情况之间的差异——请使用同级技能 ../m3/SKILL.md 和证据文档 ../../references/M3-EMPIRICAL.md。以下防御性代码片段 （移除 <think>、重试 base_resp、读取缓存 token）同样适用于 M3。

何时使用 M2.7，何时不使用——决策表

工作负载	结论	原因
标注／分类（输出 5-15 个 token）	✅ 使用纯版 MiniMax-M2.7	对于短输出，纯版速度比 -highspeed 快 2.5 倍（约 150 个 token 时出现交叉点）。
摘要／长篇内容生成	✅ 使用 -highspeed	输出超过 150 个 token 时，-highspeed 表现更佳。渐近吞吐量约为 50 TPS（并非方案所声称的 100 TPS）。
交易信号 JSON 输出	✅ 可用于生产环境	使用严格的系统提示词，在 L1+L2+L3 层级中验证结果为 6/6。置信度校准良好。
金融理论解释	✅ 研究生水平	Black-Scholes 推导、FTAP、KKT、波动率偏斜微观结构均正确。
长上下文检索（≤ 30K 个 token）	✅ 4/4 精准检索	不存在“中间丢失”效应。在 10/50/85/98% 位置均能完美检索。
工具编排（Agent 循环）	✅ 4/4 正确选择	并行和串联工具调用均可正常工作。能妥善拒绝无关查询。
N≥50 条收益率的数学／Black-Scholes／Sharpe	❌ 请勿使用	推理 token 数达到 8-16K 时会饱和；应转用 Python（numpy/scipy/cvxpy）。
QP／约束优化（Markowitz）	❌ 请勿使用	存在相同的饱和模式。请使用 scipy.optimize／cvxpy。
真实数据上的风险指标（N=252 条收益率）	❌ 请勿使用	即使是单个指标也会饱和。传入前应先汇总数据。
图表形态识别	❌ 请勿使用	会在纯噪声中幻觉出形态。请使用 TA-Lib／CV／经典算法。
代码生成（最终可部署代码）	⚠️ 仅可用于搭建脚手架	编译成功率为 100%，首次运行成功率为 0%（会幻觉出库导入语句）。请在沙盒中验证。
视觉／图像输入	❌ 不支持	M2.7 仅支持文本。image_url 会在输入层被静默丢弃。
TTS／视频	⚠️ 受方案限制	端点已存在（/v1/t2a_v2、/v1/video_generation），但在 Plus-High-Speed 上会返回错误 2061。
嵌入（批量 RAG）	⚠️ RPM 限制严格	/v1/embeddings 可访问，但调用次数超过约 5 次后会受到速率限制。请使用本地嵌入。

---

生产环境的 10 条规则

1. 始终设置系统提示词——最多持平，通常净收益为正。 messages[0] 中的长指令按约 70% 的费率计费，而且会替代 MiniMax 隐藏的约 30 个 token 默认提示词。详细指令应放在 system 角色中，绝不要放在用户内容中。

2. 显示前，从 content 中剥除 ``。 M 系列会在 content 字符串中暴露其推理轨迹。生产环境中使用：re.sub(r"\s*", "", content)。在服务端剥除 assistant 重放内容以计费（多轮对话不会重复计费）。

3. 对于非简单任务，max_tokens ≥ 1024。512 是会导致输出静默为空的陷阱。 推理会在可见内容生成前消耗预算。应防御性地检查 finish_reason == "length"。

4. 相信能力参数，对控制参数保持怀疑。 会被遵从的参数：tools、messages、max_tokens、temperature、stream。会被静默丢弃的参数：stop、tool_choice、response_format、流式 usage、image_url、messages[].name。

5. 要生成 JSON，请通过提示词工程实现——response_format 会被静默丢弃。 严格的系统提示词 + temperature=0.2 + max_tokens=4096 + try/except json.loads = 100% 可靠（已验证 6/6）。

6. 短输出工作负载（<150 个可见 token）使用普通 MiniMax-M2.7；长篇输出使用 -highspeed。 对短输出而言，“Highspeed”反而更慢（Karakeep 标记任务只有 5-15 个 token 时，普通版快 2.5 倍）。

7. 在 MiniMax 上，缓存只降低成本，不降低延迟。 在系统消息中添加 cache_control: {type: "ephemeral"}，可将输入 token 成本降低约 95%；不要期待它带来交互体验上的延迟改善。约在 prompt_tokens 达到 600+ 时激活。前缀匹配有效（用户内容变化、系统内容稳定时，命中率约为 70%）。

8. 将金融数学运算交给 Python——当 N≥50 个收益率时，M2.7 在 QP / 数值积分 / Sharpe 计算上会达到性能瓶颈。 预先汇总统计量（均值 / 标准差 / n）并传入；M2.7 可以处理最后一步公式。将金融基础运算定义为工具，用于 Agent 循环编排。

9. 绝不要在未经沙箱验证的情况下信任 M2.7 生成的代码。 compile() 不够。M2.7 会虚构库导入（从 backtesting.lib 导入 SMA、RSI、BollingerBands——这些都不存在）。应在子进程中运行 + 捕获退出代码 + 在失败时迭代修复。

10. 没有 HTTP 429——限流响应的 HTTP 状态码为 200，且 base_resp.status_code=1002。 监测 HTTP 状态码的标准重试中间件无法捕获这种情况。应使用基于代码前缀的处理器：1xxx 系列 = 退避重试；2xxx 系列 = 修正请求，不要重试。

---

规范化 Tier F Agentic 技术栈（量化-大模型工作流）

F4: long-context retrieval         → M2.7 finds facts from filings/research
        ↓
F2: structured judgment as JSON    → M2.7 emits trade signal
        ↓
F6: tool orchestration             → M2.7 selects + calls tools (parallel + chained)
        ↓
F1+F8+F9: Python math layer        → numpy/scipy/cvxpy compute deterministically
        ↓
F3: textbook explanation           → M2.7 narrates the result with theory
        ↓
F5: sandbox-validated code         → M2.7 scaffolds; subprocess validates

模式：M2.7 用于判断 / 理论 / 编排；Python 用于数学计算 / 验证 / 模式检测。对于复杂问题，绝不要在一个提示词中混合“解释 + 计算”——上下文饱和是导致失败的原因。

基元	M2.7 的作用	Python 的作用	结论
F1 Math	❌ 容量饱和	✅ scipy/numpy 计算	仅 Python
F2 JSON	✅ 在各种场景中提供 6/6 个交易信号	解析 + 执行	M2.7 + Py
F3 Theory	✅ 研究生级别的 Black-Scholes / FTAP / KKT	渲染 Markdown	仅 M2.7
F4 Long-ctx	✅ 在 27K 个 token 中实现 4/4 针尖检索	❌ 在客户端预先标记 Items（防止编造）	M2.7 + Py 防护
F5 Codegen	仅搭建脚手架——会虚构库导入	✅ 必须通过 subprocess 验证	M2.7 + Py 验证器
F6 Tools	✅ 4/4 编排 + 并行调用	执行工具主体	M2.7 + Py
F7 Patterns	❌ 在随机游走中产生幻觉	✅ TA-Lib / CV / 经典算法	仅 Python
F8 Optim	❌ 在 QP 上容量饱和	✅ scipy.optimize / cvxpy	仅 Python
F9 Risk	❌ 在 N=252 个收益值上容量饱和	✅ numpy 收益 / 回撤	仅 Python
F10 Mandarin	✅ 在量化内容上与英文相当或更优	翻译 + 直通	M2.7（有注意事项）

---

防御性代码片段（可直接复制粘贴）

删除 <think> 标签并处理 finish_reason

import re

def parse_minimax_response(response: dict) -> tuple[str, str | None]:
    """Returns (visible_content, error_class).
    error_class is None for normal responses; set when finish_reason indicates issues."""
    choice = response["choices"][0]
    raw_content = choice.get("message", {}).get("content", "")
    finish = choice.get("finish_reason")

    # Strip reasoning trace
    visible = re.sub(r"<think>[\s\S]*?</think>\s*", "", raw_content).strip()

    # Defensive: detect saturation (per iter-36/37 — empty visible + length finish)
    if finish == "length" and len(visible) < 50:
        usage = response.get("usage", {})
        reasoning_tokens = (usage.get("completion_tokens_details") or {}).get("reasoning_tokens", 0)
        max_tokens = usage.get("completion_tokens", 0)
        if reasoning_tokens >= max_tokens * 0.95:
            return visible, "saturated"
    if finish == "length":
        return visible, "truncated"
    return visible, None

适用于生产环境的 JSON 输出（不依赖 response_format）

SYSTEM_PROMPT = """You are a trading signal generator. Output ONLY a JSON object with these exact 5 fields:
{
  "action": "long" | "short" | "flat",
  "confidence": <0.0 to 1.0>,
  "reasoning": "<one sentence explaining the setup>",
  "stop_loss_pct": <number, 0 if action=flat>,
  "take_profit_pct": <number, 0 if action=flat>
}
No markdown, no prose before or after, no code fences. Just the JSON object."""

# call with temperature=0.2, max_tokens=4096, model="MiniMax-M2.7-highspeed"
# then: signal = json.loads(parse_minimax_response(resp)[0])

支持前缀匹配的缓存友好型系统提示词

def build_messages(user_input: str, stable_system: str) -> list[dict]:
    """stable_system varies per service but is constant per call. Cached after first call,
    re-used across varying user_input (~70% hit rate on prefix match)."""
    return [
        {
            "role": "system",
            "content": stable_system,
            "cache_control": {"type": "ephemeral"},  # Anthropic-style; honored by MiniMax
        },
        {"role": "user", "content": user_input},
    ]

# For short system prompts (<300 tokens), pad to ≥600 to ACTIVATE caching.
# Counterintuitive: more bytes = lower billable tokens once cached.

感知速率限制的重试（无 HTTP 429——解析 base_resp）

import time

def call_with_retry(client_fn, body: dict, max_attempts: int = 5) -> dict:
    """MiniMax returns HTTP 200 + base_resp.status_code=1002 on rate limit.
    Standard HTTP-status-based middleware will NOT catch this."""
    for attempt in range(max_attempts):
        resp = client_fn(body)
        base_resp = resp.get("base_resp", {})
        code = base_resp.get("status_code", 0)
        if code == 0:
            return resp
        if code == 1002:  # rate limit
            time.sleep(2 ** attempt)
            continue
        if code in (1004, 2013, 2061):  # auth / params / plan-gated — don't retry
            raise RuntimeError(f"MiniMax error {code}: {base_resp.get('status_msg')}")
        raise RuntimeError(f"Unknown MiniMax error {code}: {base_resp.get('status_msg')}")
    raise RuntimeError("MiniMax rate limit persisted across max attempts")

缓存 token 读取器（兼容两种 API 格式）

def get_cached_tokens(usage: dict) -> int:
    """MiniMax uses BOTH OpenAI-style (auto-cache) and Anthropic-style (explicit cache_control).
    Production parsers must handle BOTH variants."""
    pt_details = usage.get("prompt_tokens_details") or {}
    return (
        pt_details.get("cached_tokens", 0)               # OpenAI shape
        or usage.get("cache_read_input_tokens", 0)       # Anthropic shape
        or 0
    )

---

11 种已记录的失败模式——防御措施

幻觉（6 个实例）——在输入不确定时编造看似合理的细节

领域	编造的内容	防御措施
JSON 强制	未使用 response_format，却返回类似 JSON 的自然语言	优化提示词；使用 try/except json.loads
视觉输入	没有拒绝，而是就缺失的图像进行推理	不要将 M2.7 用于视觉任务；预先进行 OCR
10-K 来源引用	编造“Source: ITEM 3”归属	在客户端预先标记输入；事后验证
库导入	backtesting.lib 中的 SMA、RSI（并不存在）	在沙箱中执行；迭代修复
图表形态	在纯 GBM 噪声中得出“下降三角形看涨突破”	使用 TA-Lib / CV；不要询问 M2.7
置信度处理	（反例——校准确实正确；更普遍的模式不止于此）	使用确定性替代方案进行交叉验证

检测启发式：reasoning_tokens > 2.5× baseline 与幻觉相关（根据 iter-35）。标记以供审核。

饱和（4 个实例）——在不可能的数学问题上耗尽推理预算

任务	预算	症状	防御
Sharpe（N=10）	4K	可见内容为空；预算为 16K 时成功	预先总结；转交 Python
Black-Scholes	16K	N(d1)/N(d2) 计算始终未收敛	不要使用 M2.7；使用 scipy.stats.norm.cdf
Markowitz QP	8K	尝试求解 KKT；预算耗尽	使用 scipy.optimize / cvxpy
Sortino（N=252）	8K	逐值跟踪消耗了 token	预先总结聚合结果

检测启发式：is_saturated = (finish_reason=='length' AND len(visible)<50 AND reasoning_tokens >= 0.95*max_tokens)。不要用更高预算重试——改为转交 Python。

跨语言不对称（1 个实例）

查询	英文回复	中文回复
1989 年天安门事件	完整的历史叙述，包括“屠杀”一词	委婉回避（“我不太清楚...换个话题”）

防御：对于有多语言用户的 amonic 服务，检测非实质性回复（内容简短 + 使用表示不确定的措辞）。金融用例不太可能遇到此问题。国际版 api.minimax.io 会对政治敏感内容应用中文专属过滤；对应的英文内容则未经过滤。

---

API 接口概览（Plus-High-Speed 计划）

端点	URL	请求体格式	受计划限制？	备注
聊天补全	/v1/chat/completions	OpenAI 兼容格式（6 个参数被静默丢弃）	否	主要接口
模型目录	/v1/models	OpenAI 兼容格式	否	此层级有 7 个模型
嵌入	/v1/embeddings	MiniMax 格式（texts/type/vectors）	受 RPM 限制	多分钟冷却；不适用于批量 RAG
文件（CRUD）	/v1/files/{list,upload,delete}	子资源操作动词	否	完整 CRUD；int64 file_id（存在 JS 精度风险）
TTS	/v1/t2a_v2	MiniMax 原生格式	是	全部 6 个语音模型均受限（2061）
视频	/v1/video_generation	MiniMax 原生格式，异步	是	task_id 轮询模式（未经测试）
视觉（image_url）	（输入时丢弃）	OpenAI 兼容格式	不适用	M2.7 不支持——纯文本模型
Web 搜索 MCP	tools: [{type: "web_search"}]	OpenAI 兼容格式	是	本次测试中首次出现 HTTP 400（2013“not support”）

---

运维事实

主题	事实
并发最佳点	对聊天补全而言，p=10（真正并行，吞吐量约为串行的 5 倍）。p=20 只能再提升 25%。
TPS 渐近值	高速模式下约为 50 tokens/sec（并非套餐所宣称的 100 TPS）。生产容量基准按 40 TPS 计算。
最低延迟下限	每次调用约为 1.5s（网络 + 分词 + 推理前置开销）——无论提示词大小如何，都无法低于此值。
上下文上限	200K tokens（介于 142K 和 262K 之间）。安全运行值：100K。Token 与字节的比例：英文每个 token 对应 3.6 个字符
缓存激活	约 600+ 个 prompt_tokens 时自动缓存；显式设置 cache_control 也有效；前缀匹配的命中率约为 70%
缓存 TTL	≥ 3 分钟（测试的 185s 内无衰减）；上限可能为 5 分钟
流式分块形态	粗粒度（每块约 125 个字符，每秒约 2 块）。不是逐 token 输出。<think> 会被拆分到多个块中。
普通话 token 成本	对于语义内容相同的文本，普通话消耗的 token 是英文的 1.4–1.5 倍（CJK 的 BPE 特性）

---

OPS 工具 — 模型升级检测

本次探索活动实现了一个主动预警机制：当 MiniMax 发布新模型时，定期轮询会检测到并以非零状态退出，强制重新验证。参见 scripts/minimax-check-upgrade（在 iter-16 中移植）和 references/model-upgrade-detection.md。

# After install + lock-snapshot setup:
~/path/to/minimax-check-upgrade
# Exit 0 = no change (live matches locked snapshot)
# Exit 1 = upgrade detected (review diff before bumping lock)
# Exit 2 = fetch error

建议通过 launchd/cron 设置每日运行。在 CI 中将其设为合并前检查，若目录发生变化但未经明确的锁定审查，则拒绝变更。

---

深入参考资料（查阅详情）

• references/RETROSPECTIVE.md — 41 轮迭代回顾（TL;DR、10 条首要规则、Agentic 技术栈、完整故障模式目录、API 接口、运维事实、未解问题）
• references/quirks.md — 按用例组织的关键发现（开头列出 5 条生产环境必知事项）
• references/api-patterns/INDEX.md — 40 份逐端点模式文档的可导航目录
• references/api-patterns/<endpoint>.md — 最小可行请求/响应格式、惯用代码片段、已知故障模式、复现命令、每次探测的完整溯源信息
• references/fixtures/ — 精选的原始 API 响应，用于与未来的 API 变更进行差异比较
• scripts/minimax-check-upgrade — 模型升级检测可执行文件
• templates/launchd-check-upgrade.plist — 每日轮询 plist 模板

---

新建 amonic 服务的快速入门

# 1. Set environment
export OPENAI_BASE_URL=https://api.minimax.io/v1
export OPENAI_API_KEY=<from 1Password>
export MINIMAX_MODEL=MiniMax-M2.7              # for tagging-style services
# OR: export MINIMAX_MODEL=MiniMax-M2.7-highspeed   # for long-form services

# 2. Verify wiring
curl -sS -X POST "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model": "MiniMax-M2.7", "messages": [{"role": "user", "content": "Reply OK"}], "max_tokens": 200}' \
  | python3 -m json.tool | head -20

# 3. Add cache_control to your stable system prompt for ~95% input cost reduction (see snippet above)
# 4. Add the strip-<think> + finish_reason check to your response parser
# 5. Add base_resp.status_code rate-limit handler (no HTTP 429)
# 6. If using mise: schedule check-upgrade as a pre-merge CI gate

---

来源

内容整理自 ~/own/amonic/minimax/ 中进行的 41 轮 minimax-m27-explore 自主循环探索活动：

• 40 份经验证的实践模式文档（api-patterns/*.md）
• 1 份特性汇总（quirks/CLAUDE.md — iter-11）
• 1 份回顾（RETROSPECTIVE.md — iter-42）
• 1 个 OPS 工具及其 launchd plist（bin/minimax-check-upgrade + config/plists/）
• 约 50 份 API 响应样本
• 约 155 条非显而易见的经验、35 项关键发现、11 种已记录的故障模式、4 类错误代码系列、6 类兼容性封装

探索活动于 2026-04-28 至 2026-04-29 期间针对 MiniMax-M2.7-highspeed 进行了验证。使用 mise run minimax:check-upgrade 对新模型版本重新验证。

执行后反思

0. 确认文件位置。 — 编辑前，确认此 SKILL.md 是权威文件。
1. 哪里出错了？ — 接线代码片段失效了，某个参数之前被报告为“静默丢弃”，现在却能成功，或者 base_resp.status_code 映射发生了变化。更新受影响的模式文档和这里的表格，避免后续读者重蹈覆辙。
2. 哪里发生了漂移？ — mise run minimax:check-upgrade 检测到新模型版本，OpenAI 兼容的封装结构发生变化，或者速率限制／cache_control 语义有所改变。更新锁定快照指针和受影响的章节。
3. 记录下来。 — 在“来源记录”下追加一条带日期的记录（或新建“演进日志”章节），说明触发原因、修复方法和证据，以便未来的迭代审查漂移。