TR ▾

Python'da MiniMax API: OpenAI SDK'sını kullanın

Bu API'yi Python'dan çağırmak için özel bir istemciye ihtiyacınız yok. Base URL ve anahtarı ayarladıktan sonra standart openai paketi çalışır; bu rehber sohbet, akış, JSON, araçlar, yeniden deneme ve maliyet hesaplamasını kapsar.

Güncellendi

Python'un bir API'yi çağırdığını temsil eden, yığılmış API katmanlarının arasından geçen parlayan kod parantezleri

Temel noktalar

  • openai paketini yükleyin, ardından istemciye base_url https://api.minimaxapikey.com/v1 ve anahtarınızı geçirin.
  • Sohbet, akış, JSON modu ve fonksiyon çağırma için uncensored model kimliğini kullanın.
  • HTTP 429 hatalarını geri çekilme ile yönetin ve tam anahtar için 8'e, deneme anahtarı için 2'ye kadar iş parçacığı sınırını uygulayın.
  • Her yanıtın kullanımını okuyun ve harcamayı takip etmek için 1M token başına $0.15 ve $0.50 ile çarpın.

Kurulum ve ilk çağrı

minimax api python çalışması için en hızlı yol PyPI'deki resmi openai paketidir. Bu sitenin arkasındaki hizmet, bağımsız bir sağlayıcı tarafından barındırılan OpenAI uyumlu bir API'dir; öğrenilecek ayrı bir SDK yoktur. Bu, satıcının kendi platformu değildir ve standart bir OpenAI betiğinden tek farklar base URL, anahtar ve model adıdır.

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)

Anahtarı API anahtarı sayfası adresinden alın. Yeni hesaplar tek tıkla, kart gerekmeden orada $0.50 deneme kredisi talep edebilir ve bu kredi 7 gün boyunca geçerliliğini korur. Anahtarı kaynak dosyalara yapıştırmak yerine gösterildiği gibi bir ortam değişkeninde tutun.

Örneklemleme parametreleri ve max_tokens

Genel ayarlar aktarılır: temperature, top_p, stop, seed ve frekans ve presence cezaları. Düşük sıcaklıkta sabit bir seed, testler için daha tekrarlanabilir çıktılar sağlar; ancak bunu aynı metni garantilemek olarak görmeyin.

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 isteğe bağlıdır. Belirtilmezse tamamlama, promptunuzdan sonra kalan 100.000 token penceresinin tamamını kullanabilir. Bu uzun belgeler için yararlıdır, ancak üretim kodunda bir sınır belirleyin. Kontrolsüz bir üretim, gerçek çıktı token'larına ($0.50/1M) mal olur ve bir sınır, kötü bir promptun yaratacağı zararı sınırlar.

Akış yanıtları

stream=True geçirin ve döngüye girin. Yanıt sunucu tarafından gönderilen olaylar olarak iletilir ve SDK bunları chunk nesnelerine dönüştürür. Duyarlı bir sohbet arayüzü için delta metni geldiğinde yazdırın.

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)

Kullanım sayıları akışın sonunda gönderilir. SDK sürümünüz son chunk'ta bir usage özniteliği açıyorsa, oradan okuyun; aksi takdirde bütçeleme için tokenları kendi tarafınızda sayın. Pratik bir nokta: akışlı bir istek, akış bitene kadar eşzamanlılık slotunu tutar. Tam anahtarınızla sekiz uzun akış açarsanız, dokuzuncu istek biri tamamlanana kadar concurrency koduyla 429 hatası alır. Slotun serbest kalması için her zaman bir akışı kapatın veya tamamen tüketin.

Yapılandırılmış çıktı için JSON modu

Makine tarafından okunabilir çıktıya ihtiyacınız olduğunda, response_format değerini bir JSON nesnesine ayarlayın. İstemde JSON'dan bahsedin ve istediğiniz anahtarları tanımlayın; çünkü format bayrağı geçerli JSON sözdizimini garanti eder, ancak şemanızı değil.

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

Sonucu hala doğrulayın. Kullanmadan önce gerekli anahtarların var olduğundan ve doğru türde olduğundan emin olun ve kodunuzun onlar yokken ne yapması gerektiğine karar verin; örneğin daha net bir talimatla bir kez yeniden denemek. İnce bir doğrulama katmanı, hatta birkaç isinstance kontrolü, üretim hata ayıklamasından tasarruf sağlar.

Araç çağırma

Araç çağırma OpenAI formatını izler. tools içinde işlevleri tanımlarsınız, isteğe bağlı olarak tool_choice ile bir seçim zorunlu kılarsınız ve model tool_calls ile JSON argümanları döndürür. İşlevi çalıştırın ve sonucu role: "tool" ile bir mesaj olarak geri gönderin.

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)

Bu örnekteki oranlar demo için uydurulmuştur. Gerçek kodda işlev kendi hizmetinizi çağırmalıdır. Bir model bazen hatalı argümanlar üretebileceğinden, argümanları bir try bloğu içinde json.loads ile savunmacı bir şekilde ayrıştırın.

Hız limitleri, yeniden denemeler ve eşzamanlı işler

Tam anahtar 8 eşzamanlı istek ve dakikada 300 istek yapmanıza izin verir; deneme anahtarı dakikada 2 eşzamanlı ve 60 istek yapmanıza izin verir. Limiti aşmanız HTTP 429 hatası döndürür. Hata kodu dakikalık limit için rate_limited, eşzamanlı çağrı limiti için concurrency şeklindedir. Geçici aşırı yüklenme de 429 hatası verir ve Retry-After: 5 başlığı gönderilir. OpenAI SDK bazı hataları otomatik olarak yeniden dener; bu davranışı max_retries ile artırabilirsiniz. Toplu işler için, yeniden deneme ile limiti aşmak yerine, kendi iş parçacığı limitinizi ekleyerek tasarımı gereği limiti aşmamanızı sağlayın.

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

Deneme anahtarı için max_workers=2 kullanın. Asenkron istemci AsyncOpenAI aynı argümanları alır; aynı üst sınırı uygulamak için bunu bir asyncio.Semaphore(8) ile eşleştirin. Dokümantasyon, limitler için inceleyebileceğiniz yanıt başlıklarını listeler.

Sohbet geçmişini koruma

API durum bilgisi tutmaz. Önceki çağrıyı hatırlamaz, bu nedenle çoklu tur sohbeti her seferinde tüm konuşmayı göndererek çalışır. Bir mesaj listesi tutun, kullanıcı turunu ekleyin, API'yi çağırın ve bir sonraki turdan önce asistan yanıtını ekleyin.

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

Bu desen, her adımda artan bir maliyete sahiptir: her istek, önceki tüm adımları girdi token'ları olarak öder. 100.000 token'lık bir pencereniz varsa geniş bir alanınız vardır, ancak uzun oturumlar pahalı ve yavaş hale gelir. Basit bir politika, sistem mesajını ve son N adımı korumak veya modelden eski adımların kısa bir özetini isteyip onları bununla değiştirmektir. Bir politika seçin, çünkü bir sohbet uygulamasına sonradan kırpma eklemek, baştan kurmaktan daha zordur.

429 dışı hataların yönetimi

SDK türü belirli istisnalar yükseltir ve bunları sınıflandırmak birkaç satır değerindedir. Kimlik doğrulama sorunları ve hatalı istekler yeniden denemede düzelmez; ağ hataları ve aşırı yüklenme genellikle düzelir. Bunları farklı şekilde ele alın.

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

Destek ile iletişime geçtiğinizde, başarısız çağrının X-Request-Id değerini dahil edin. Bu tam isteği tanımlar. Varsayılan uzun olduğu için gösterildiği gibi açık bir timeout ayarlayın; eşzamanlılık slotunu tutan takılı bir çağrı verimliliğinizi sessizce düşürür. Başarısız veya reddedilen istekler ücretlendirilmez, bu nedenle başarısız bir çağrıyı yeniden denemek faturayı iki katına çıkarmaz.

Ölçeklenecek küçük bir proje düzeni

Betikler hizmetlere dönüşür. Başlangıçtaki küçük bir yapı, API ayrıntılarını tek bir yerde tutar; böylece model adı, zaman aşımı veya limitlerdeki bir sonraki değişiklik yirmi dosya yerine tek bir dosyayı etkiler.

# 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

Diğer tüm modüller complete'i içe aktarır ve istemci oluşturmaz. Bu tek bağlantı noktası, daha sonra günlük kaydı, harcama sayacı veya bir semaför eklemek için kullanılan yerdir. Daha fazla referans materyal istiyorsanız, dokümantasyon sayfası aynı uç noktaları curl formatında gösterir; bu, başarısız bir Python çağrısını bilinen iyi bir istekle karşılaştırmak için kullanışlıdır.

Sürüm sabitleme de yardımcı olur. requirements dosyanızda openai paketini sabitleyin ve sürüm notlarını okuyarak bilinçli bir şekilde yükseltin; çünkü SDK değişiklikleri istisna adlarını veya varsayılan yeniden deneme davranışını değiştirebilir. Bunu, yeni bir takım arkadaşının ilk günden itibaren sormadan çalıştırabilmesi için hangi base URL ve model ID'nin beklendiğini belirten kısa bir README notuyla eşleştirin.

Testler konusunda bir son nokta. Kredi harcamaması veya ağa bağımlı kalmaması için en az bir test, sahte bir istemci ile çalışacak şekilde yazın. Gerçek API'deki değişiklikleri erken yakalamak için tek bir canlı smoke testini elle veya günlük bir işle çalıştırın.

Koddaki bakiye ve maliyet takibi

Her yanıt X-Balance-USD taşır ve SDK başlıkları with_raw_response üzerinden okumanıza olanak tanır. Her çağrının ardından günlüğe kaydetmek, kullanıcılarınız fark etmeden önce tükenmiş bir bakiyeyi yakalamanın ucuz bir yoludur.

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

Formülün çalıştırılmış bir kontrolü: 2.000 girdi tokenı ve 500 çıktı tokenı olan bir çağrı, girdi için 2.000 x 0.15 / 1.000.000 = $0.0003 ve çıktı için 500 x 0.50 / 1.000.000 = $0.00025 maliyetine sahiptir; yani $0.00055. Bin böyle çağrı $0.55 eder. Başarısız veya reddedilen istekler ücretlendirilmez; bu nedenle başarılı kullanım nesnelerinden oluşturulan bir günlük fatura ile yakından eşleşecektir.

Faturalandırma, abonelik olmadan ön ödemeli krediden kullandıkça öde esasına göredir. Bakiye yüklemeleri $20 ile $500 arasında herhangi bir tam miktarda yapılır, $50'den itibaren bonuslar sağlanır ve kredi hiç sona ermez; ayrıntılar fiyatlandırma sayfası adresindedir. İstemler eğitim için kullanılmaz.

Sorular ve cevaplar

Ayrı bir MiniMax Python paketi var mı?

Burada buna ihtiyacınız yok. Bu hizmet OpenAI ile uyumlu olduğu için, normal openai paketi özel bir base_url ile çalışır. Bu bağımsız bir hizmettir, satıcının resmi SDK'si değildir.

Asenkron istemci çalışıyor mu?

Evet. AsyncOpenAI aynı base_url ve api_key argümanlarını alır. Aktif istek sayısını eşzamanlılık limitinize eşit veya altında tutun.

Token sayılarını nasıl alırım?

Akışsız her yanıt, prompt_tokens ve completion_tokens içeren bir usage nesnesi içerir. Akışlar için kullanım bilgisi sona eklenir, bu nedenle istemciniz bunu son parça olarak sunuyorsa oradan okuyun.

Hangi bağlam uzunluğunu kullanabilirim?

Pencere 100.000 token'dır ve prompt ile tamamlama arasında paylaşılır. max_tokens isteğe bağlıdır.

Anahtarınız tek bir formun uzağında

Bir hesap oluşturun, anahtarı kopyalayın ve base URL'yi değiştirin. Kurulum bu kadar basit.

API anahtarı al