PL ▾

MiniMax API w Pythonie: Użyj SDK OpenAI

Nie potrzebujesz specjalnego klienta do wywoływania tego API z Pythona. Standardowy pakiet openai działa po ustawieniu base_url i klucza, a ten przewodnik obejmuje czat, strumieniowanie, JSON, narzędzia, ponowne próby i kalkulację kosztów.

Zaktualizowano

Wstęga świecąca nawiasów kodowych przeplatająca się przez warstwy API, reprezentująca Pythona wywołującego API

Kluczowe punkty

  • Zainstaluj openai, a następnie przekaż base_url https://api.minimaxapikey.com/v1 i swój klucz do klienta.
  • Użyj ID modelu uncensored do czatu, strumieniowania, trybu JSON i wywoływania narzędzi.
  • Obsłuż HTTP 429 z eksponencjalnym wzrostem opóźnienia i ogranicz liczbę wątków do 8 dla pełnego klucza i 2 dla klucza próbnego.
  • Odczytuj zużycie z każdej odpowiedzi i mnoż przez $0,15 i $0,50 za 1 mln tokenów, aby śledzić wydatki.

Zainstaluj i wykonaj pierwsze wywołanie

Dla minimax api python najszybszą drogą jest oficjalny pakiet openai z PyPI. Usługa za tą stroną to API kompatybilne z OpenAI, uruchamiane przez niezależnego dostawcę, więc nie ma osobnego SDK do nauki. Nie jest to platforma samego dostawcy, a jedyne zmiany względem standardowego skryptu OpenAI to adres URL bazowy, klucz i nazwa modelu.

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)

Pobierz klucz ze strony klucza API. Nowe konta mogą uzyskać $0,50 kredytu próbnego jednym kliknięciem bez karty, ważny przez 7 dni. Przechowuj klucz w zmiennej środowiskowej, jak pokazano, zamiast wklejać go do plików źródłowych.

Parametry próbkowania i max_tokens

Standardowe parametry są przekazywane: temperature, top_p, stop, seed oraz kary za częstotliwość i obecność. Stały seed przy niskiej temperaturze daje bardziej powtarzalne wyniki do testów, choć nie traktuj tego jako gwarancji identycznego tekstu.

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 jest opcjonalne. Bez niego uzupełnienie może wykorzystać wszystko, co zostało z okna 100 000 tokenów po Twoim prompcie. Jest to przydatne przy długich dokumentach, ale w kodzie produkcyjnym ustaw limit. Niekontrolowana generacja zużywa prawdziwe tokeny wyjściowe w cenie $0,50 za 1 mln, a limit stawia sufit na szkodach spowodowanych złym promptem.

Odpowiedzi strumieniowe

Przekaż stream=True i iteruj. Odpowiedź jest dostarczana jako zdarzenia wysyłane przez serwer, a SDK przekształca je na obiekty z fragmentami. Wyświetlaj tekst fragmentu, gdy przychodzi, dla interfejsu czatu, który działa responsywnie.

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)

Dane o zużyciu są wysyłane na końcu strumienia. Jeśli wersja Twojego SDK udostępnia atrybut usage w ostatnim fragmencie, odczytaj go tam; w przeciwnym razie policz tokeny po swojej stronie do celów budżetowych. Jedna praktyczna uwaga: żądanie strumieniowe zajmuje slot współbieżności do momentu zakończenia strumienia. Jeśli otworzysz osiem długich strumieni z pełnym kluczem, dziewiąte żądanie otrzyma błąd 429 z kodem concurrency, dopóki jedno się nie zakończy. Zawsze zamykaj lub w pełni konsumuj strumień, aby zwolnić slot.

Tryb JSON dla strukturalnego outputu

Gdy potrzebujesz wyniku czytelnego dla maszyny, ustaw response_format na obiekt JSON. Wspomnij o JSON w prompcie i opisz pożądane klucze, ponieważ flaga formatu gwarantuje poprawną składnię JSON, ale nie twój schemat.

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

Nadal waliduj wynik. Sprawdź, czy wymagane klucze istnieją i mają odpowiednie typy przed ich użyciem i zdecyduj, co twój kod robi, gdy ich nie ma, np. ponawiając raz z wyraźniejszą instrukcją. Cienka warstwa walidacji, nawet kilka sprawdzeń isinstance, oszczędza dużo debugowania produkcyjnego.

Wywoływanie narzędzi

Wywoływanie narzędzi podąża za kształtem OpenAI. Opisujesz funkcje w tools, opcjonalnie wymuszasz wybór z tool_choice, a model zwraca tool_calls z argumentami JSON. Uruchamiasz funkcję i wysyłasz wynik z powrotem jako wiadomość z 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)

Stawki w tym przykładzie są fikcyjne dla demonstracji. W prawdziwym kodzie funkcja wywołałaby twoją własną usługę. Parsuj argumenty defensywnie z json.loads w bloku try, ponieważ model może czasami emitować niepoprawne argumenty.

Limity zapytań, ponowne próby i praca równoległa

Pełny klucz pozwala na 8 równoległych zapytań i 300 na minutę; klucz próbny pozwala na 2 równoległe i 60 na minutę. Przekroczenie zwraca HTTP 429. Kod błędu to rate_limited dla limitu na minutę i concurrency dla zbyt wielu jednoczesnych wywołań. Tymczasowe przeciążenie również zwraca 429 z nagłówkiem Retry-After: 5. SDK OpenAI ponawia niektóre niepowodzenia automatycznie, a Ty możesz to zwiększyć za pomocą max_retries. Dla zadań wsadowych dodaj własny limit wątków, aby mieścić się w limicie z założenia, a nie poprzez ponawianie.

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

Użyj max_workers=2 z kluczem próbnym. Klient asynchroniczny, AsyncOpenAI, przyjmuje te same argumenty; połącz go z asyncio.Semaphore(8), aby wymusić ten sam limit. Dokumentacja zawiera nagłówki odpowiedzi, które możesz sprawdzić pod kątem limitów.

Zachowywanie historii rozmowy

API jest bezstanowe. Nie pamięta poprzedniego wywołania, więc czat wieloetapowy działa poprzez wysyłanie całej rozmowy za każdym razem. Przechowuj listę wiadomości, dołączaj turę użytkownika, wywołaj API, a następnie dołącz odpowiedź asystenta przed następną rundą.

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

Ten wzorzec ma koszt rosnący z każdą turą: każde żądanie płaci za wszystkie wcześniejsze tury ponownie jako tokeny wejściowe. Przy oknie 100 000 tokenów masz dużo miejsca, ale długie sesje stają się drogie i wolne. Prostą polityką jest zachowanie wiadomości systemowej i ostatnich N tur lub poproszenie modelu o krótkie streszczenie starszych tur i zastąpienie ich nim. Zdecyduj o polityce wcześnie, ponieważ dodawanie przycinania do aplikacji czatowej jest bardziej kłopotliwe niż zbudowanie jej od początku.

Obsługa błędów poza 429

SDK rzuca typowane wyjątki, a ich sortowanie jest warte kilku linii. Problemy z uwierzytelnianiem i błędne żądania nie naprawią się przy ponownej próbie, podczas gdy błędy sieciowe i przeciążenie zwykle tak. Traktuj je inaczej.

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

Kontaktując się z pomocą techniczną, dołącz wartość X-Request-Id z nieudanego wywołania. Identyfikuje ono dokładnie to żądanie. Ustaw jawny timeout, jak pokazano, ponieważ domyślny jest długi, a utknięte wywołanie, które zajmuje slot współbieżności, cicho zmniejsza przepustowość. Nieudane lub odrzucone żądania nie są rozliczane, więc ponowne wywołanie nieudanej operacji nie podwaja rachunku.

Mały układ projektu, który skaluje się

Skrypty przekształcają się w usługi. Mała struktura na początku pozwala umieścić szczegóły API w jednym miejscu, więc późniejsza zmiana nazwy modelu, limitu czasu lub limitów dotyka tylko jednego pliku zamiast dwudziestu.

# 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

Każdy inny moduł importuje complete i nigdy nie buduje klienta. To pojedyncze miejsce to miejsce, gdzie dodasz logowanie, licznik wydatków lub semafor później. Jeśli chcesz więcej materiałów referencyjnych, strona dokumentacji pokazuje te same endpointy w formie curl, co jest przydatne do porównania nieudanego wywołania Pythona z znanym poprawnym żądaniem.

Przydatne jest też blokowanie wersji. Zablokuj pakiet openai w pliku wymagań i aktualizuj go celowo, czytając najpierw notatki wydania, ponieważ zmiany w SDK mogą zmieniać nazwy wyjątków lub domyślne zachowanie ponawiania. Połącz to z krótką notatką w README, która wskazuje, jaki adres URL bazowy i identyfikator modelu oczekuje projekt, aby nowy współpracownik mógł go uruchomić od pierwszego dnia bez pytań.

Ostatnia uwaga dotycząca testowania. Napisz przynajmniej jeden test, który działa na fałszywym kliencie, aby Twój zestaw testów nie wydawał kredytu ani nie zależała od sieci. Zostaw jeden test smoke na żywym API, uruchamiany ręcznie lub w zadaniu nocnym, aby wychwycić zmiany w rzeczywistym API jak najszybciej.

Śledzenie salda i kosztów w kodzie

Każda odpowiedź zawiera X-Balance-USD, a SDK pozwala odczytywać nagłówki przez with_raw_response. Logowanie tego po każdym wywołaniu to tani sposób na złapanie wyczerpanego salda przed użytkownikami.

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

Przeliczenie wzoru: wywołanie z 2 000 tokenami wejściowymi i 500 wyjściowymi kosztuje 2 000 x 0,15 / 1 000 000 = $0,0003 za wejście, plus 500 x 0,50 / 1 000 000 = $0,00025 za wyjście, więc $0,00055. Tysiąc takich wywołań daje $0,55. Nieudane lub odrzucone żądania nie są rozliczane, więc dziennik zbudowany z udanych obiektów usage będzie blisko zgodny z rachunkiem.

Rozliczenie odbywa się w modelu pay-as-you-go z przedpłaconego kredytu bez subskrypcji. Doładowania wynoszą od $20 do $500 w dowolnej całkowitej kwocie, z bonusami od $50, a kredyt nigdy nie wygasa; szczegóły są na stronie z cenami. Prompty nie są używane do trenowania.

Pytania i odpowiedzi

Czy istnieje osobny pakiet MiniMax dla Pythona?

Nie ma potrzeby go tutaj instalować. Usługa jest kompatybilna z OpenAI, więc zwykły pakiet openai działa z niestandardowym base_url. Jest to niezależna usługa, a nie oficjalne SDK dostawcy.

Czy klient async działa?

Tak. AsyncOpenAI przyjmuje te same argumenty base_url i api_key. Utrzymuj liczbę aktywnych zapytań na poziomie lub poniżej limitu współbieżności.

Jak uzyskać liczbę tokenów?

Każda odpowiedź niestrumieniowa zawiera obiekt usage z prompt_tokens i completion_tokens. W strumieniowaniu usage jest wysyłane na końcu, więc odczytaj je z ostatniego chunka, jeśli klient go udostępnia.

Jaka jest maksymalna długość kontekstu?

Okno kontekstu wynosi 100 000 tokenów, dzielonych między prompt a completion. max_tokens jest opcjonalne.

Twój klucz jest o jeden formularz stąd

Utwórz konto, skopiuj klucz, zmień bazowy URL. To cała konfiguracja.

Pobierz klucz API