واجهة MiniMax API في Python: استخدم حزمة OpenAI
لا تحتاج إلى عميل خاص لاستدعاء هذه الواجهة من Python. تعمل الحزمة القياسية openai بمجرد ضبط عنوان URL الأساسي والمفتاح، ويغطي هذا الدليل الدردشة، والبث، ووضع JSON، والأدوات، وإعادة المحاولة وحساب التكاليف.
محدّث

نقاط رئيسية
- ثبّت openai، ثم مرر base_url https://api.minimaxapikey.com/v1 ومفتاحك إلى العميل.
- استخدم معرف النموذج uncensored للدردشة، والبث المتدفق، ووضع JSON، واستدعاء الأدوات.
- عالج خطأ HTTP 429 باستخدام التراجع، وحدد عدد الخيوط بـ 8 للمفتاح الكامل، و2 لمفتاح التجربة.
- اقرأ الاستخدام من كل استجابة واضربه في $0.15 و $0.50 لكل مليون رمز (token) لتتبع الإنفاق.
التثبيت وإجراء أول طلب
للعمل مع minimax api python، فإن أسرع طريقة هي استخدام الحزمة الرسمية openai من PyPI. الخدمة خلف هذا الموقع هي واجهة API مستضافة ومتوافقة مع OpenAI يديرها مزود مستقل، لذا لا توجد حزمة SDK منفصلة للتعلم عليها. ليست منصة البائع الخاصة، والتغييرات الوحيدة عن نص OpenAI القياسي هي عنوان 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 رمز بعد الموجّه الخاص بك. هذا مفيد للمستندات الطويلة، لكن ضع حداً أقصى في أكواد الإنتاج. تكلفة التوليد غير المقيدة هي رموز مخرجات حقيقية بمعدل $0.50 لكل مليون رمز، ويضع الحد الأقصى سقفًا للضرر الناتج عن موجّه سيئ.
استجابات البث المتدفق
مرر stream=True وكرّر عبر الاستجابة. يتم تسليم الاستجابة كحدث يرسله الخادم (SSE)، وتحوّلها مكتبة SDK إلى كائنات chunk. اطبع نص الفاصل مع وصوله للحصول على واجهة دردشة تبدو متجاوبة.
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 على الجزء الأخير، فاقرأها هناك؛ وإلا فاحسب الرموز من جانبك للميزانية. نقطة عملية: يحتفظ الطلب المتدفق بخانة التزامن الخاصة به حتى ينتهي البث المتدفق. إذا فتحت ثمانية بثوث طويلة على مفتاح كامل، فسيحصل الطلب التاسع على خطأ 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، ويعيد النموذج tool_calls مع وسائط JSON. تشغل الدالة وترسل النتيجة مرة أخرى كرسالة مع 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)
معدلات هذا المثال وهمية للعرض التجريبي. في الكود الحقيقي، ستستدعي الدالة خدمتك الخاصة. قم بتحليل الوسائط بشكل دفاعي مع json.loads داخل كتلة try، لأن النموذج يمكن أن يصدر وسائط مشوهة أحياناً.
حدّ المعدل، إعادة المحاولة، والعمل المتزامن
المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة؛ يسمح مفتاح التجربة بـ 2 متزامن و60 في الدقيقة. يؤدي التجاوز إلى HTTP 429. رمز الخطأ هو rate_limited لحدّ المعدل في الدقيقة وconcurrency لعدد كبير جدًا من المكالمات المتزامنة. يؤدي الحمل الزائد المؤقت أيضًا إلى 429، مع رأس Retry-After: 5. يعيد OpenAI SDK بعض الأخطاء تلقائيًا، ويمكنك رفع ذلك مع max_retries. بالنسبة لمهام الدفعات (batch)، أضف حدًا خاصًا بالخيوط بحيث تبقى تحت الحد بالتصميم بدلاً من إعادة المحاولة.
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 صراحةً كما هو موضح، لأن الافتراضي طويل، ومكالمة عالقة تحتل شريحة متزامنة تقلل إنتاجيتك (throughput) بصمت. الطلبات الفاشلة أو المرفوضة لا تُحسب، لذا فإن إعادة محاولة مكالمة فاشلة لا تضاعف الفاتورة.
تخطيط مشروع صغير قابل للتوسع
تنمو السكريبتات إلى خدمات. بنية بسيطة في البداية تبقي تفاصيل الواجهة 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 ولا تبني عميلًا أبدًا. هذه النقطة الوحيدة هي المكان الذي تضيف فيه تسجيلًا، عداد إنفاق أو سيمافور (semaphore) لاحقًا. إذا كنت تريد المزيد من المواد المرجعية، فإن صفحة الوثائق تظهر نقاط النهاية نفسها في شكل curl، وهو مفيد لمقارنة مكالمة Python فاشلة مقابل طلب معروف جيدًا.
تثبيت الإصدار يساعد أيضًا. ثبت حزمة openai في ملف المتطلبات الخاص بك وقم بالترقية عن قصد، بعد قراءة ملاحظات الإصدار أولاً، لأن تغييرات SDK يمكن أن تغير أسماء الاستثناءات أو سلوك إعادة المحاولة الافتراضي. اجمع ذلك مع ملاحظة README قصيرة تحدد أي عنوان URL أساسي ومعرّف النموذج يتوقعه المشروع، حتى يتمكن زميل الفريق الجديد من تشغيله في اليوم الأول دون سؤال.
نقطة أخيرة حول الاختبار. اكتب اختباراً واحداً على الأقل يعمل ضد عميل وهمي، حتى لا تنفق مجموعتك الرصيد أو تعتمد على الشبكة. احتفظ باختبار دخان حي واحد، يتم تشغيله يدوياً أو في وظيفة ليلية، لالتقاط التغييرات في الواجهة 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 × 0.15 / 1,000,000 = $0.0003 للمدخلات، بالإضافة إلى 500 × 0.50 / 1,000,000 = $0.00025 للمخرجات، لذا $0.00055. ألف مكالمة من هذا القبيل تصل إلى $0.55. الطلبات الفاشلة أو المرفوضة لا تُحتسب، لذا فإن سجل مبني من كائنات الاستخدام الناجح سيتطابق مع الفاتورة بشكل وثيق.
الفوترة هي الدفع حسب الاستخدام من رصيد مسبق الدفع بدون اشتراك. تبدأ عمليات الشحن من $20 إلى $500 بأي مبلغ صحيح، مع مكافآت من $50، ولا ينتهي الرصيد؛ التفاصيل موجودة على صفحة الأسعار. لا تُستخدم الموجّهات للتدريب.
المزيد من الأدلة
أسئلة وأجوبة
هل يوجد حزمة Python منفصلة لـ MiniMax؟
لا تحتاج إلى واحدة هنا. هذه الخدمة متوافقة مع OpenAI، لذا فإن الحزمة openai العادية تعمل مع base_url مخصص. إنها خدمة مستقلة وليست SDK الرسمي من البائع.
هل يعمل العميل غير المتزامن؟
نعم. يأخذ AsyncOpenAI نفس وسائط base_url وapi_key. حافظ على عدد الطلبات النشطة عند أو أقل من حدّ التزامن الخاص بك.
كيف أحصل على تعداد الرموز؟
تحتوي كل استجابة غير متدفقة على كائن usage يحتوي على prompt_tokens وcompletion_tokens. بالنسبة للاستجابات المتدفقة، يُرسل usage في النهاية، لذا اقرأه من الجزء (chunk) الأخير إذا كان عميلك يعرضها.
ما هو طول السياق الذي يمكنني استخدامه؟
النافذة هي 100,000 رمز، مشتركة بين الموجّه والإكمال. max_tokens اختياري.
مفتاحك على بُعد استمارة واحدة
أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذا هو الإعداد بالكامل.