中文 ▾

MiniMax API Python:使用 OpenAI SDK

你不需要特殊的客户端即可从 Python 调用此 API。设置 base URL 和密钥后,标准的 openai 包即可使用。本指南涵盖聊天、流式输出、JSON、工具、重试和成本计算。

更新于

发光的代码括号交织在堆叠的 API 层之间,代表 Python 调用 API

要点

  • 安装 openai,然后将 base_url https://api.minimaxapikey.com/v1 和你的密钥传递给客户端。
  • 使用模型 ID uncensored 进行聊天、流式输出、JSON 模式和工具调用。
  • 处理 HTTP 429 错误并采用退避策略,完整密钥最多允许 8 个线程,试用密钥最多允许 2 个线程。
  • 从每个响应中读取使用情况,并分别乘以每 1M token $0.15 和 $0.50 的单价以跟踪支出。

安装并进行首次调用

要在 Python 中使用 MiniMax API,最快的方式是使用来自 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,以及频率和存在惩罚。使用低 temperature 和固定 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 个 token 窗口中的剩余部分。这对长文档很有用,但在生产代码中应设置上限。失控的生成会消耗真实的输出 token,价格为每 1M $0.50,上限可以限制坏提示词造成的损害。

流式响应

传递 stream=True 并迭代。响应以服务器发送事件的形式交付,SDK 将其转换为 chunk 对象。随着 delta 文本的到达打印它们,让聊天界面响应更灵敏。

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 版本在最后一个 chunk 上暴露了 usage 属性,请在此处读取;否则,请在你的端侧计算 token 以进行预算。一个实际的问题是:流式请求会占用其并发槽位直到流结束。如果你在完整密钥上打开八个长流,第九个请求将获得 429 错误,代码为 concurrency,直到其中一个完成。始终关闭或完全消耗流,以便释放槽位。

用于结构化输出的 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"])

仍然需要验证结果。在使用它们之前,检查所需的键是否存在且具有正确的类型,并决定当它们不存在时你的代码该怎么做,例如用更清晰的指令重试一次。薄薄的验证层,即使是几个 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 个并发请求和每分钟 300 次请求;试用密钥允许 2 个并发请求和每分钟 60 次请求。超出限制将返回 HTTP 429 错误。每分钟请求上限的错误代码为 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."))

这种模式随着每一轮对话而增加成本:每个请求都要为所有早期轮次作为输入 token 付费。在 100,000 token 的窗口下你有很大空间,但长会话会变得昂贵且缓慢。一个简单的策略是保留系统消息和最后 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 细节保留在一个地方,以便以后更改模型名称、超时或限制时只影响一个文件而不是二十个。

# 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 更改可能会改变异常名称或默认重试行为。配合简短的 README 说明项目期望哪个 base URL 和模型 ID,以便新队友第一天就能运行它而无需询问。

关于测试的最后一件事。编写至少一个针对假客户端运行的测试,以便你的套件不消耗额度或依赖网络。保留一个手动运行或在夜间作业中运行的实时冒烟测试,以便尽早捕获真实 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 个输入 token 和 500 个输出 token,输入费用为 2,000 x 0.15 / 1,000,000 = $0.0003,输出费用为 500 x 0.50 / 1,000,000 = $0.00025,总计 $0.00055。一千次此类调用总计 $0.55。失败或被拒绝的请求不收费,因此基于成功使用情况对象生成的日志将与账单高度一致。

计费方式为从预付额度中按量付费,无订阅。充值金额从 $20 到 $500 不等,可以是任意整美元金额,充值 $50 及以上可获得奖励,且额度永不过期;详情请见 定价页面。提示词不会用于模型训练。

问答

是否有独立的 MiniMax Python 包?

这里不需要。该服务兼容 OpenAI,因此常规 openai 包配合自定义 base_url 即可使用。这是一个独立服务,并非厂商的官方 SDK。

异步客户端是否可用?

可用。AsyncOpenAI 接受相同的 base_url 和 api_key 参数。保持并发请求数不超过你的并发限制。

如何获取 token 计数?

每个非流式响应都包含带有 prompt_tokens 和 completion_tokens 的 usage 对象。对于流式输出,usage 在末尾发送,因此如果客户端暴露了该对象,请从最后一个 chunk 中读取。

我可以使用多大的上下文长度?

上下文窗口为 100,000 个 token,由提示词和补全共享。max_tokens 是可选的。

只差一张表单,即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。

获取 API 密钥