minimax

MiniMax M-series の本番環境向け配線

https://api.minimax.io/v1 にある OpenAI 互換のチャット補完エンドポイントで、M2.7-highspeed 推論モデル（2026-04-29 時点のプレミアムティア）を使用します。OpenAI とそっくりに見えますが、OpenAI のパラメーターを 6 つ黙って無視し、content 内に <think> の推論トレースを露出します。チャット補完以外では、この API は MiniMax 独自仕様です（URL、リクエストボディの形式、エラー形式が異なり、HTTP 4xx ではなく HTTP 200 と base_resp.status_code を使用します）。

モデル自体は、金融・クオンツ業務における定性的な評価、理論の説明、ツールのオーケストレーションに優れていますが、現実的な規模のデータに対する生の計算はできません（推論予算が飽和します）。また、入力に不確実性があると、もっともらしい詳細を幻覚します（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 に基づく再試行、キャッシュ済みトークンの読み取り）は、変更なしで M3 に適用できます。

---

M2.7 を使う場合と使わない場合 — 判断表

ワークロード	判定	理由
タグ付け／分類（5-15 トークンの出力）	✅ 通常の MiniMax-M2.7 を使用	短い出力では通常版は -highspeed より 2.5 倍高速です（約 150 トークンで逆転します）。
要約／長文生成	✅ -highspeed を使用	150 トークンを超えると -highspeed が優勢です。約 50 TPS に収束します（プランの 100 TPS という説明とは異なります）。
トレードシグナルの JSON 出力	✅ 本番環境で使用可能	厳密なシステムプロンプトを使用した場合、L1+L2+L3 レイヤー全体で 6/6 を確認済みです。信頼度も適切に調整されています。
金融理論の解説	✅ 大学院レベル	Black-Scholes の導出、FTAP、KKT、ボラティリティ・スキューのマイクロストラクチャーはいずれも正確です。
長いコンテキストからの検索（≤ 30K トークン）	✅ 4/4 で要点を検索	「中間での見落とし」効果はありません。10/50/85/98% の各位置で完璧に検索できます。
ツールのオーケストレーション（エージェントループ）	✅ 4/4 で正しく選択	並列および連鎖型のツール呼び出しが機能します。関連性のないクエリも適切に拒否します。
N≥50 件のリターンに対する数学／Black-Scholes／Sharpe	❌ 使用しない	推論トークンが 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トークンのデフォルト指示も置き換えます。詳細な指示はシステムロールに記述し、ユーザーコンテンツには絶対に記述しないでください。

2. 表示する前に、content から `` を取り除いてください。 M シリーズは、コンテンツ文字列内に推論トレースを出力します。本番環境では、re.sub(r"\s*", "", content) を使用してください。アシスタントの再送信時には、サーバー側で課金対象から取り除いてください（マルチターンでも二重課金されません）。

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未満）には通常の MiniMax-M2.7、長文には -highspeed を使用してください。 「Highspeed」は短い出力では直感に反して遅くなります（Karakeep のタグ付けを5～15トークンで行う場合、通常版は2.5倍高速です）。

7. MiniMax でのキャッシュはコストのみを削減し、レイテンシは改善しません。 システムメッセージに cache_control: {type: "ephemeral"} を追加すると、入力トークンのコストを約95％削減できます。対話型 UX のレイテンシ改善は期待しないでください。約600以上の prompt_tokens で有効になります。プレフィックス一致が機能するため、ユーザー部分が変動しシステム部分が安定している場合、約70％のヒット率になります。

8. 金融計算は Python に任せてください。M2.7 は N≥50 のリターンを対象とする QP／数値積分／Sharpe 計算で飽和します。 集計値（平均／標準偏差／n）を事前に要約して渡し、M2.7 には最後の計算式を処理させてください。エージェントループのオーケストレーションでは、金融計算の基本関数を TOOLS として定義してください。

9. M2.7 が生成したコードを、サンドボックスで検証せずに信用してはいけません。 compile() だけでは不十分です。M2.7 は存在しないライブラリのインポートをでっち上げます（backtesting.lib から SMA、RSI、BollingerBands をインポートするなど）。サブプロセスで実行し、終了コードを取得して、失敗した場合は反復的に修正してください。

10. HTTP 429 は返されません。レート制限されたレスポンスも、HTTP 200 + base_resp.status_code=1002 になります。 HTTP ステータスを監視する標準的な再試行ミドルウェアでは、これを検出できません。コードプレフィックスに基づくハンドラーを使用してください。1xxx 系はバックオフ付きで再試行し、2xxx 系はリクエストを修正し、再試行しないでください。

---

Canonical Tier F エージェント型スタック（quant-LLM ワークフロー）

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 を使います。複雑な問題で「説明＋計算」を1つのプロンプトに混在させないでください。飽和が失敗の原因になります。

プリミティブ	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 トークンで重要箇所の検索を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	✅ quant の内容では英語と同等以上	翻訳＋そのまま通過	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")

キャッシュ済みトークンの読み取り（両方の 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 風の自然言語を返した	プロンプトを調整する。json.loads を try/except で囲む
Vision 入力	拒否する代わりに、画像がないことについて推論した	M2.7 を Vision に使わず、事前に 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	値ごとの追跡でトークンを消費	集計値を事前に要約する

検出ヒューリスティック：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「未対応」）

---

運用上の事実

トピック	事実
並行処理の最適値	チャット補完では p=10（真の並列処理で、逐次処理に比べてスループットは約5倍）です。p=20にしても、得られる向上は25％にとどまります。
TPSの漸近値	高速プランでは約50トークン／秒です（プランでうたわれている100 TPSではありません）。本番環境の容量の基準値には40 TPSを使用してください。
最小レイテンシの下限	呼び出しごとに約1.5秒です（ネットワーク＋トークン化＋推論の前置処理）。プロンプトのサイズにかかわらず、これを下回ることはできません。
コンテキスト上限	200Kトークンです（142K〜262Kの範囲）。安全な運用上限は100Kです。英語のトークン／バイト比は1トークンあたり3.6文字です。
キャッシュの有効化	約600以上のprompt_tokensで自動キャッシュされます。明示的なcache_controlも機能し、プレフィックスが一致した場合のヒット率は約70％です。
キャッシュTTL	3分以上です（テストした185秒間、減衰はありませんでした）。上限はおそらく5分です。
ストリームチャンクの形状	粗い粒度です（1チャンクあたり約125文字、約2回／秒）。トークン単位ではありません。<think>はチャンク間で分割されます。
中国語のトークンコスト	同等の意味内容を英語で表現する場合の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のルール、エージェント型スタック、失敗モードの全カタログ、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）
• launchd plistを備えたOPSツール1件（bin/minimax-check-upgrade＋config/plists/）
• APIレスポンスのフィクスチャ約50件
• 155件のNon-Obvious Learnings、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. 記録する。 — 「Provenance」の下に日付入りの行を追記する（または新しい「Evolution log」セクションを設ける）し、きっかけ＋修正＋証拠を記録して、将来の反復で変化を監査できるようにしてください。