JA ▾

PythonでのMiniMax API:OpenAI SDKを使用

PythonからこのAPIを呼び出すのに特別なクライアントは不要です。base URLとキーを設定すれば標準のopenaiパッケージが動作し、このガイドではチャット、ストリーミング、JSON、ツール、リトライ、コスト計算を扱います。

更新

PythonがAPIを呼び出す様子を表す、積み重なったAPIレイヤーを縫うように光るコード括弧のリボン

主なポイント

  • openaiをインストールし、base_url https://api.minimaxapikey.com/v1とキーをクライアントに渡します。
  • チャット、ストリーミング、JSONモード、関数呼び出しにモデルID uncensoredを使用します。
  • HTTP 429をバックオフで処理し、フルキーはスレッド数を8、トライアルキーは2に制限します。
  • 各応答からusageを読み取り、1Mトークンあたり$0.15と$0.50を乗じて支出を追跡します。

インストールと最初の呼び出し

minimax api pythonを動作させるには、PyPIの公式openaiパッケージが最も簡単な方法です。このサイト背後のサービスは独立したプロバイダが運営するホストされたOpenAI互換APIであり、学ぶべき別個のSDKはありません。ベンダー独自のプラットフォームではなく、標準のOpenAIスクリプトからの変更点はBase URL、キー、モデル名だけです。

pip install --upgrade openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Answer in plain English, briefly."},
        {"role": "user", "content": "What does a context window limit?"},
    ],
)
print(resp.choices[0].message.content)
print(resp.usage)

APIキーのページからキーを取得します。新規アカウントはカード不要でワンクリックで$0.50の無料トライアルクレジットを取得でき、7日間有効です。ソースファイルに貼り付けるのではなく、環境変数にキーを保持してください。

サンプリングパラメータとmax_tokens

一般的なパラメータはそのまま渡されます:temperature、top_p、stop、seed、および頻度ペナルティと存在ペナルティ。低い温度で固定のseedを使用するとテストでより再現性の高い出力が得られますが、完全に同一のテキストが保証されるわけではない点に注意してください。

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "List five verbs for a changelog."}],
    temperature=0.3,
    top_p=0.9,
    stop=["\n\n"],
    seed=42,
    max_tokens=120,
)

max_tokensはオプションです。指定しない場合、プロンプト後の100,000トークンのコンテキストウィンドウの残分を使って補完が生成されます。これは長いドキュメントには有用ですが、本番コードでは上限を設定してください。暴走する生成は1Mトークンあたり$0.50で実際の出力トークンを消費し、上限を設定することでプロンプトの失敗による被害を制限できます。

ストリーミングレスポンス

stream=Trueを渡してイテレートします。応答はサーバー送信イベントとして配信され、SDKはそれらをチャンクオブジェクトに変換します。チャットインターフェースでレスポンシブな感覚を得るために、到着するたびにデルタテキストを出力してください。

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a short product description for a notebook."}],
    stream=True,
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
text = "".join(parts)

使用量はストリームの末尾に送信されます。お使いのSDKのバージョンで最後のチャンクにusage属性が公開されている場合は、そこで読み取ってください。それ以外の場合は、予算管理のためにクライアント側でトークンをカウントしてください。実用的な注意点として、ストリーミングリクエストはストリームが終了するまで同時実行数の枠を保持します。フルキーで8つの長いストリームを開くと、9番目のリクエストは完了するまでconcurrencyコードの429エラーを受け取ります。必ずストリームを閉じるか完全に消費して、枠を解放してください。

構造化出力のためのJSONモード

機械可読な出力が必要な場合は、response_formatをJSONオブジェクトに設定します。プロンプトにJSONについて言及し、必要なキーを記述してください。フォーマットフラグは有効なJSON構文を保証しますが、スキーマは保証しないためです。

import json

resp = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Reply only with JSON using keys: title, tags (list of strings)."},
        {"role": "user", "content": "Summarise: a tutorial on caching HTTP responses in Python."},
    ],
    response_format={"type": "json_object"},
)

data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])

それでも結果は必ず検証してください。必要なキーが存在し、正しい型を持っているか確認してから使用し、存在しない場合にコードがどう振る舞うか(例えば、より明確な指示で1回リトライするなど)を決定してください。薄い検証レイヤー(isinstanceチェック数個など)でも、本番環境のデバッグ工数を大幅に削減できます。

関数呼び出し

関数呼び出しはOpenAIの形式に従います。toolsで関数を定義し、tool_choiceで選択を指定し、モデルはJSON引数付きのtool_callsを返します。関数を実行し、role: "tool"メッセージとして結果を送り返します。

import json

def get_rate(currency):
    rates = {"EUR": 0.92, "GBP": 0.79}
    return json.dumps({"currency": currency, "per_usd": rates.get(currency)})

tools = [{
    "type": "function",
    "function": {
        "name": "get_rate",
        "description": "Exchange rate per 1 USD for a currency code.",
        "parameters": {
            "type": "object",
            "properties": {"currency": {"type": "string"}},
            "required": ["currency"],
        },
    },
}]

messages = [{"role": "user", "content": "How many EUR is 50 USD?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
messages.append(msg)

for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": get_rate(args["currency"])})

final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)

この例の料金はデモ用に作成された架空のものです。実際のコードでは、関数は独自のサービスを呼び出します。モデルがまれに無効な引数を出力することがあるため、tryブロック内でjson.loadsで防御的に引数を解析してください。

レート制限、リトライ、並列処理

通常キーは8つの同時リクエストと1分あたり300リクエストまで、トライアルキーは2つの同時リクエストと1分あたり60リクエストまで許可します。上限を超えるとHTTP 429が返されます。エラーコードは、1分あたりの上限に対してはrate_limited、同時リクエスト数の上限に対してはconcurrencyです。一時的な過負荷でも429が返され、Retry-After: 5ヘッダーが付加されます。OpenAI SDKは一部の失敗を自動で再試行しますが、max_retriesでその数を増やすこともできます。バッチジョブでは、再試行に頼るのではなく、スレッド数に独自の制限を設けて上限内に収まるように設計してください。

from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI, RateLimitError
import os, time

client = OpenAI(
    base_url="https://api.minimaxapikey.com/v1",
    api_key=os.environ["UNCENSORED_KEY"],
    max_retries=2,
)

def ask(prompt):
    for attempt in range(4):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=200,
            )
            return r.choices[0].message.content
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    return None

prompts = [f"Write one tagline for product {i}." for i in range(20)]
with ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(ask, prompts))

トライアルキーではmax_workers=2を使用します。非同期クライアントAsyncOpenAIは同じ引数を受け取ります。同じ上限を適用するためにasyncio.Semaphore(8)と組み合わせてください。制限を確認できるレスポンスヘッダーのリストはドキュメントに記載されています。

会話履歴の保持

APIはステートレスです。前の呼び出しを記憶しないため、マルチターンチャットでは毎回会話全体を送信する必要があります。メッセージのリストを保持し、ユーザーのターンを追加し、APIを呼び出し、次のラウンドの前にアシスタントの返信を追加します。

history = [{"role": "system", "content": "You are a patient Python tutor."}]

def chat(user_text):
    history.append({"role": "user", "content": user_text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

print(chat("What is a list comprehension?"))
print(chat("Show me one with a filter."))

このパターンは、ターンごとにコストが増加します。各リクエストは、入力トークンとして以前のすべてのターンに対して課金されます。100,000トークンのコンテキストウィンドウがあれば余裕がありますが、長いセッションは高価で遅くなります。単純なポリシーとして、システムメッセージと最後のNターンを保持するか、モデルに古いターンの短い要約を依頼し、それらを要約に置き換えます。チャットアプリに後からトリミングを追加するよりも、早い段階でポリシーを決定してください。

429以外のエラー処理

SDKは型付き例外を発生させ、それらを分類するのは価値のある作業です。認証問題と不正なリクエストはリトライで解消されませんが、ネットワークエラーと過負荷は通常解消されます。これらを区別して扱ってください。

import openai

try:
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Hello"}],
        timeout=60,
    )
except openai.AuthenticationError:
    print("Check the API key and the Bearer header.")
except openai.RateLimitError as e:
    print("Slow down:", e.response.headers.get("Retry-After"))
except openai.APIConnectionError:
    print("Network problem, retry with backoff.")
except openai.APIStatusError as e:
    print("Server said", e.status_code, e.response.headers.get("X-Request-Id"))

サポートに連絡する際は、失敗した呼び出しのX-Request-Idの値を含めてください。これは特定のリクエストを識別します。デフォルトは長いため、明示的なtimeoutを設定してください。並列スロットを保持したままの呼び出しはスループットを静かに低下させます。失敗または拒否されたリクエストは課金されないため、失敗した呼び出しをリトライしても請求が倍増することはありません。

スケーラブルな小さなプロジェクト構成

スクリプトはサービスへと成長します。初期の段階で少し構造を作っておけば、APIの詳細が1か所に集まるため、モデル名、タイムアウト、制限の変更が20ファイルではなく1ファイルだけで済みます。

# llm.py
import os
from openai import OpenAI

BASE_URL = "https://api.minimaxapikey.com/v1"
MODEL = "uncensored"

_client = OpenAI(base_url=BASE_URL, api_key=os.environ["UNCENSORED_KEY"], timeout=60, max_retries=2)

def complete(messages, **kwargs):
    r = _client.chat.completions.create(model=MODEL, messages=messages, **kwargs)
    return r.choices[0].message.content, r.usage

他のすべてのモジュールはcompleteをインポートし、クライアントを構築しません。この単一の接合部が、後からロギング、支出カウンター、セマフォを追加する場所です。より多くのリファレンス資料が必要な場合は、ドキュメントページで同じエンドポイントをcurl形式で示しており、失敗したPython呼び出しを既知の正常なリクエストと比較するのに役立ちます。

バージョンの固定も役立ちます。requirementsファイルでopenaiパッケージを固定し、リリースノートをまず読んでから意図的にアップグレードしてください。SDKの変更は例外の名前やデフォルトのリトライ動作を変更する可能性があるためです。プロジェクトが期待するBase URLとモデルIDを明記した短いREADMEノートも追加し、新しいチームメイトが1日目から実行できるようにしてください。

テストに関する最後のポイント。フェイククライアントに対して実行する少なくとも1つのテストを書いて、テストスイートがクレジットを消費したりネットワークに依存したりしないようにしてください。単一のライブスモークテストを手動または毎晩のジョブで実行し、実際のAPIの変更を早期に検出してください。

コードでの残高とコストの追跡

すべての応答にはX-Balance-USDが含まれており、SDKはwith_raw_responseを通じてヘッダーを読み取ることができます。各呼び出し後にログに記録するのは、ユーザーが気づく前に残高が枯渇したことを検知する安価な方法です。

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in French."}],
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
resp = raw.parse()

def cost_usd(usage):
    return usage.prompt_tokens * 0.15 / 1_000_000 + usage.completion_tokens * 0.50 / 1_000_000

print(cost_usd(resp.usage))

計算による検証例:2,000入力トークンと500出力トークンの呼び出しは、入力に対して2,000 x 0.15 / 1,000,000 = $0.0003、出力に対して500 x 0.50 / 1,000,000 = $0.00025、合計$0.00055かかります。そのような呼び出し1,000回で$0.55になります。失敗または拒否されたリクエストは課金されないため、成功したusageオブジェクトから構築されたログは請求額とほぼ一致します。

課金はサブスクリプションなしの前払いクレジットからの従量制です。チャージは$20から$500までの任意の整数額で実行でき、$50以上でボーナスがあり、クレジットは期限切れになりません。詳細は料金ページに記載されています。プロンプトはトレーニングに使用されません。

質問と回答

専用のMiniMax Pythonパッケージはありますか?

ここでは不要です。このサービスはOpenAI互換なので、カスタムbase_urlで通常のopenaiパッケージが動作します。ベンダー公式SDKとは独立したサービスです。

非同期クライアントは動作しますか?

はい。AsyncOpenAIは同じbase_urlとapi_key引数を受け取ります。同時実行リクエスト数は同時実行数の上限以下に保ってください。

トークン数はどのように取得しますか?

ストリーミングでない応答には、prompt_tokensとcompletion_tokensを含むusageオブジェクトがあります。ストリーミングでは最終チャンクでusageが送信されるため、クライアントが公開している場合はそこから読み取ってください。

使用可能なコンテキスト長は?

ウィンドウは100,000トークンで、プロンプトとcompletionで共有されます。max_tokensはオプションです。

キーはフォーム 1 つで手に入ります

アカウントを作成し、キーをコピーし、ベースURLを変更します。これでセットアップは完了です。

API キーを取得