VI ▾

API MiniMax bằng Python: Sử dụng SDK OpenAI

Bạn không cần client đặc biệt để gọi API này từ Python. Gói openai tiêu chuẩn hoạt động sau khi bạn đặt base URL và khóa, và hướng dẫn này bao gồm chat, streaming, JSON, tools, retries và tính toán chi phí.

Cập nhật

Dải ngoặc mã sáng lấp lánh đan xen qua các lớp API xếp chồng, đại diện cho Python gọi API

Điểm chính

  • Cài đặt openai, sau đó truyền base_url https://api.minimaxapikey.com/v1 và khóa của bạn vào client.
  • Sử dụng model ID uncensored cho chat, streaming, chế độ JSON và gọi hàm.
  • Xử lý HTTP 429 bằng backoff, và giới hạn threads ở mức 8 cho khóa đầy đủ, 2 cho khóa dùng thử.
  • Đọc usage từ mỗi phản hồi và nhân với $0.15 và $0.50 trên 1M token để theo dõi chi tiêu.

Cài đặt và thực hiện cuộc gọi đầu tiên

Để minimax api python hoạt động, cách nhanh nhất là dùng gói chính thức openai từ PyPI. Dịch vụ đằng sau trang này là một API tương thích OpenAI được chạy bởi nhà cung cấp độc lập, nên bạn không cần học một SDK riêng biệt. Đây không phải nền tảng của nhà cung cấp gốc, và những thay đổi duy nhất so với script OpenAI tiêu chuẩn là base URL, khóa API và tên mô hình.

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)

Lấy khóa từ trang khóa API. Tài khoản mới có thể nhận $0.50 tín dụng dùng thử chỉ với một cú nhấp, không cần thẻ, và nó hợp lệ trong 7 ngày. Hãy giữ khóa trong biến môi trường như minh họa thay vì dán vào tệp nguồn.

Các tham số lấy mẫu và max_tokens

Các tham số thông dụng được truyền thẳng: temperature, top_p, stop, seed, và các hình phạt frequency và presence. Một seed cố định với nhiệt độ thấp cho bạn đầu ra lặp lại hơn cho các bài kiểm tra, dù bạn không nên coi đó là bảo đảm văn bản giống hệt nhau.

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 là tùy chọn. Không có nó, phần hoàn thành có thể dùng bất kỳ token nào còn lại của cửa sổ 100,000 token sau prompt của bạn. Điều này hữu ích cho tài liệu dài, nhưng hãy đặt giới hạn trong mã sản xuất. Một lần tạo chạy mất kiểm soát tốn token đầu ra thực tế với giá $0.50 trên 1M, và giới hạn đặt trần cho thiệt hại từ một prompt xấu.

Phản hồi streaming

Truyền stream=True và lặp qua. Phản hồi được gửi dưới dạng sự kiện gửi bởi máy chủ, và SDK chuyển chúng thành các đối tượng chunk. In văn bản delta khi nó đến để có giao diện chat phản hồi nhanh.

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)

Số liệu sử dụng được gửi ở cuối luồng. Nếu phiên bản SDK của bạn cho phép truy cập thuộc tính usage trên chunk cuối cùng, hãy đọc tại đó; nếu không, hãy tự đếm token để quản lý ngân sách. Một điểm thực tế: một yêu cầu truyền phát giữ slot độ đồng thời của nó cho đến khi luồng kết thúc. Nếu bạn mở tám luồng dài trên một khóa đầy đủ, yêu cầu thứ chín sẽ nhận lỗi 429 với mã concurrency cho đến khi một luồng hoàn tất. Luôn đóng hoặc tiêu thụ đầy đủ một luồng để giải phóng slot.

Chế độ JSON cho đầu ra có cấu trúc

Khi bạn cần đầu ra đọc được bằng máy, hãy đặt response_format thành một đối tượng JSON. Đề cập đến JSON trong prompt, và mô tả các khóa bạn muốn, vì cờ định dạng bảo đảm cú pháp JSON hợp lệ nhưng không bảo đảm schema của bạn.

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"])

Vẫn hãy xác thực kết quả. Kiểm tra xem các khóa bắt buộc có tồn tại và có đúng kiểu không trước khi dùng chúng, và quyết định mã của bạn làm gì khi chúng không có, chẳng hạn như thử lại một lần với hướng dẫn rõ ràng hơn. Một lớp xác thực mỏng, thậm chí chỉ vài kiểm tra isinstance, tiết kiệm rất nhiều thời gian gỡ lỗi sản xuất.

Gọi hàm

Gọi hàm theo cấu trúc OpenAI. Bạn mô tả các hàm trong tools, tùy chọn ép buộc lựa chọn với tool_choice, và model trả về tool_calls với các đối số JSON. Bạn chạy hàm và gửi kết quả lại dưới dạng tin nhắn với 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)

Các mức giá trong ví dụ này được tạo ra cho bản demo. Trong mã thực tế, hàm sẽ gọi dịch vụ của riêng bạn. Hãy phân tích các đối số một cách phòng thủ bằng json.loads bên trong khối try, vì mô hình đôi khi có thể phát ra các đối số bị lỗi cú pháp.

Giới hạn tốc độ, thử lại và công việc song song

Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 mỗi phút; khóa dùng thử cho phép 2 đồng thời và 60 mỗi phút. Vượt quá sẽ trả về HTTP 429. Mã lỗi là rate_limited cho giới hạn mỗi phút và concurrency cho quá nhiều lệnh gọi đồng thời. Quá tải tạm thời cũng trả về 429, với tiêu đề Retry-After: 5. SDK OpenAI tự động thử lại một số lỗi, và bạn có thể tăng điều này với max_retries. Đối với công việc batch, hãy thêm giới hạn threads của riêng bạn để bạn nằm dưới giới hạn theo thiết kế thay vì bằng cách thử lại.

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))

Sử dụng max_workers=2 trên khóa dùng thử. Client async, AsyncOpenAI, nhận cùng các đối số; hãy ghép nó với asyncio.Semaphore(8) để áp dụng cùng trần đó. Tài liệu liệt kê các tiêu đề phản hồi bạn có thể kiểm tra để xem giới hạn.

Giữ lịch sử hội thoại

API là stateless. Nó không nhớ lệnh gọi trước đó, nên chat đa lượt hoạt động bằng cách gửi toàn bộ cuộc trò chuyện mỗi lần. Hãy giữ một danh sách tin nhắn, thêm lượt người dùng, gọi API, rồi thêm phản hồi trợ lý trước vòng tiếp theo.

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."))

Mẫu này có chi phí tăng lên với mỗi lượt: mỗi yêu cầu trả tiền cho tất cả các lượt trước đó lại dưới dạng token đầu vào. Với cửa sổ 100,000 token, bạn có nhiều không gian, nhưng các phiên dài sẽ tốn kém và chậm. Một chính sách đơn giản là giữ tin nhắn hệ thống và N lượt cuối, hoặc yêu cầu model tóm tắt ngắn các lượt cũ và thay thế chúng bằng bản tóm tắt đó. Hãy quyết định chính sách sớm, vì việc thêm cắt xén vào ứng dụng chat sau này khó hơn nhiều so với việc xây dựng nó ngay từ đầu.

Xử lý lỗi ngoài 429

SDK ném các ngoại lệ có kiểu, và phân loại chúng đáng giá vài dòng. Lỗi xác thực và yêu cầu xấu sẽ không tự sửa khi thử lại, trong khi lỗi mạng và quá tải thường sẽ. Hãy xử lý chúng khác nhau.

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"))

Khi liên hệ hỗ trợ, hãy bao gồm giá trị của X-Request-Id từ lệnh gọi bị lỗi. Nó xác định chính xác yêu cầu đó. Đặt timeout rõ ràng như minh họa, vì giá trị mặc định dài, và một lệnh gọi bị treo giữ slot concurrency sẽ âm thầm cắt giảm thông lượng của bạn. Các yêu cầu thất bại hoặc bị từ chối không bị tính phí, nên thử lại một lệnh gọi thất bại không làm tăng hóa đơn lên gấp đôi.

Cấu trúc dự án nhỏ nhưng có thể mở rộng

Script phát triển thành dịch vụ. Một chút cấu trúc ngay từ đầu giữ các chi tiết API ở một nơi, để một thay đổi sau này về tên model, timeout hoặc giới hạn chỉ chạm vào một tệp thay vì hai mươi.

# 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

Mọi mô-đun khác đều nhập complete và không bao giờ tạo client. Điểm nối duy nhất này là nơi bạn thêm ghi nhật ký, bộ đếm chi tiêu hoặc semaphore sau này. Nếu bạn muốn thêm tài liệu tham khảo, trang tài liệu hiển thị cùng các endpoint dưới dạng curl, rất hữu ích để so sánh một lệnh gọi Python bị lỗi với một yêu cầu đã biết là hoạt động tốt.

Ghim phiên bản cũng giúp ích. Hãy ghim gói openai trong tệp requirements của bạn và nâng cấp có chủ đích, đọc ghi chú phát hành trước, vì thay đổi SDK có thể làm thay đổi tên ngoại lệ hoặc hành vi thử lại mặc định. Hãy ghép điều đó với ghi chú README ngắn nêu rõ base URL và model ID mà dự án mong đợi, để một đồng nghiệp mới có thể chạy nó vào ngày đầu tiên mà không cần hỏi.

Một điểm cuối cùng về kiểm thử. Hãy viết ít nhất một kiểm thử chạy với client giả, để bộ kiểm thử của bạn không tiêu tốn tín dụng hoặc phụ thuộc vào mạng. Hãy giữ một smoke test chạy thật duy nhất, chạy thủ công hoặc trong công việc hàng đêm, để bắt kịp thay đổi trong API thực sớm.

Theo dõi số dư và chi phí trong mã

Mọi phản hồi đều mang theo X-Balance-USD, và SDK cho phép bạn đọc các tiêu đề thông qua with_raw_response. Ghi lại giá trị này vào log sau mỗi lệnh gọi là một cách rẻ tiền để phát hiện khi số dư cạn kiệt trước khi người dùng của bạn làm vậy.

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))

Một ví dụ kiểm tra công thức: một lệnh gọi với 2.000 token đầu vào và 500 token đầu ra tốn 2.000 x 0,15 / 1.000.000 = $0,0003 cho đầu vào, cộng 500 x 0,50 / 1.000.000 = $0,00025 cho đầu ra, vậy tổng là $0,00055. Một nghìn lệnh gọi như vậy tốn $0,55. Các yêu cầu bị lỗi hoặc bị từ chối không được tính phí, vì vậy nhật ký được xây dựng từ các đối tượng sử dụng thành công sẽ khớp với hóa đơn một cách sát sao.

Thanh toán theo mức sử dụng từ tín dụng trả trước, không có gói đăng ký. Nạp tiền từ $20 đến $500 với bất kỳ số nguyên nào, với các khoản bonus từ $50, và tín dụng không bao giờ hết hạn; chi tiết có trên trang giá cả. Các prompt không được dùng để huấn luyện.

Hỏi đáp

Có gói Python MiniMax riêng biệt nào không?

Bạn không cần gói riêng ở đây. Dịch vụ này tương thích OpenAI, nên gói openai tiêu chuẩn hoạt động với base_url tùy chỉnh. Đây là dịch vụ độc lập, không phải SDK chính thức của nhà cung cấp.

Client bất đồng bộ có hoạt động không?

Có. AsyncOpenAI nhận cùng các tham số base_url và api_key. Hãy giữ số lượng yêu cầu đang xử lý ở mức bằng hoặc thấp hơn giới hạn concurrency của bạn.

Làm thế nào để lấy số lượng token?

Mỗi phản hồi không streaming có đối tượng usage chứa prompt_tokens và completion_tokens. Với stream, usage được gửi ở cuối, nên hãy đọc từ chunk cuối nếu client của bạn cho phép.

Độ dài ngữ cảnh nào tôi có thể sử dụng?

Cửa sổ ngữ cảnh là 100,000 token, dùng chung cho prompt và completion. max_tokens là tùy chọn.

Khóa của bạn chỉ cách một biểu mẫu

Tạo tài khoản, sao chép khóa, thay đổi URL cơ sở. Đó là toàn bộ thiết lập.

Lấy khóa API