نقاط رئيسية
- ثبّت openai، ثم أنشئ اتصال OpenAI(base_url=..., api_key=...) مع ضبط النموذج على uncensored.
- يستخدم البث المتدفق، ووضع JSON، واستدعاء الدوال المعاملات القياسية، ويعمل الوضع غير المتزامن بنفس الطريقة.
- حدد حدّ الطلبات المتزامنة بـ 8 باستخدام semaphor، واسمح لـ SDK بإعادة محاولة استجابات 429.
- اقرأ X-Balance-USD من رؤوس الاستجابة الخام لمراقبة رصيدك من داخل الكود.
مثال عملي بسيط
إليك أقصر إعداد مفيد لبروكسي واجهة برمجة تطبيقات OpenAI في Python. يفترض أن يكون لديك Python 3.9 أو أحدث، ومفتاح API من صفحة مفتاح API، والحزمة مثبتة عبر pip install openai، وتم تصدير المفتاح كمتغير بيئة UNCENSORED_API_KEY.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.openaiapiproxy.com/v1",
api_key=os.environ["UNCENSORED_API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Give me a one-line product tagline for a hiking app."}],
temperature=0.8,
max_tokens=60,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)نقطة النهاية متوافقة مع OpenAI، لكنها خدمة منفصلة. ليست واجهة برمجة التطبيقات الرسمية لـ OpenAI أو أي مورد آخر، وهي تستضيف نموذجاً واحداً، uncensored. يوجد مساران فقط: POST /v1/chat/completions و GET /v1/models، لذا التزم بواجهة إكمال المحادثة في الـ SDK.
بعض الملاحظات حول هذا الكود. يأتي المفتاح من متغير بيئة بدلاً من قيمة حرفية، لذا لا يُدرج أبداً في التحكم بالإصدارات. يحتوي كائن usage في الاستجابة على عدّ الرموز الدقيقة التي يُبنى عليها الفاتورة، وهو مفيد للتسجيل. وmax_tokens اختياري: اتركه غير محدد وسيعتمد الإكمال على باقي نافذة السياق، وهو أمر مقبول للقصص ولكنه مكلف في حلقة تحتوي على خطأ.
بث الرموز عند وصولها
يستخدم البث المتدفق أحداثاً مرسلة من الخادم. مرر stream=True وتصفح القطع. يحمل الجزء الأخير من البث استخدام الرموز، لذا تحقق من القطع التي لا تحتوي على خيارات.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Tell a two-paragraph ghost story."}],
stream=True,
)
usage = None
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if getattr(chunk, "usage", None):
usage = chunk.usage
print()
if usage:
print("tokens:", usage.prompt_tokens, usage.completion_tokens)تفاصيل تشغيلية: يشغل استدعاء البث فراغاً واحداً من فراغات التزامن الخاصة بك حتى ينتهي البث. إذا خرج الكود الخاص بك من الحلقة مبكراً، أغلق البث (stream.close()) لتحرير الفراغ.
عادةً ما تغلف تطبيق الويب هذه الحلقة في مولد (generator) ويمرر كل قطعة إلى المتصفح. مع FastAPI، يعني ذلك إرجاع StreamingResponse الذي يُعيد أجزاء النص. احتفظ بالمفتاح على الخادم في هذا التصميم. يتحدث المتصفح مع المسار الخاص بك، ويتحدث المسار الخاص بك مع الـ API، لذا لا يتم كشف المفتاح أبداً لكود العميل.
العملاء غير المتزامنين والطلبات المتزامنة
المفتاح الكامل يسمح بـ 8 طلبات في آنٍ واحد و300 طلب في الدقيقة. يسمح المفتاح التجريبي بـ 2 و60. إذا أطلقت 200 مهمة متزامنة باستخدام asyncio.gather، فستحصل على أخطاء 429 برمز concurrency. يُحلّ ذلك بواسطة قفل عدّاد (semaphore) قبل حدوثه.
import asyncio
from openai import AsyncOpenAI
client = AsyncOpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=4)
gate = asyncio.Semaphore(8)
async def ask(prompt: str) -> str:
async with gate:
r = await client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
)
return r.choices[0].message.content
async def main():
prompts = [f"Write a title for chapter {i} of a sea adventure." for i in range(1, 41)]
results = await asyncio.gather(*(ask(p) for p in prompts))
for t in results:
print(t)
asyncio.run(main())استخدم 2 كحجم للـ semaphore أثناء استخدام مفتاح التجربة. يعيد الـ SDK محاولة الاستجابات 429 مع تراجع تلقائي افتراضياً، و max_retries يزيد عدد المحاولات. في حالة الحمل الزائد المؤقت، يجيب الخادم بـ 429 مع Retry-After: 5، وهو ما يراعيه الـ SDK.
يحدّ السيمافور الطلبات النشطة داخل عملية واحدة فقط. إذا شغّلت عدة عمال، قسّم الحد بينهم: مع مفتاح كامل، يجب أن يستخدم كل عامل من أربعة عمال سيمافور بقيمة 2. حدّ الـ 300 طلب في الدقيقة مشترك بينهم جميعاً، لذا فإن طابورًا بمعدل ثابت أفضل من دفعة واحدة للمهام الكبيرة غير المتصلة. حدّ حجم الجسم البالغ 8 ميجابايت نادراً ما يكون مصدر قلق في الدردشة، لكنه ينطبق على كل طلب.
وضع JSON واستدعاء الدوال
كلاهما يعمل عبر المعلمات العادية. لوضع JSON، اضبط response_format واطلب JSON في الموجّه.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "Return JSON with keys name, mood and hook."},
{"role": "user", "content": "Invent a tavern keeper for a fantasy game."},
],
)
npc = json.loads(r.choices[0].message.content)
print(npc["name"])استدعاء الأدوات يتطلب خطوة إضافية: تقوم بتنفيذ الدالة بنفسك وإرجاع المخرجات كرسالة tool.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
tools = [{
"type": "function",
"function": {
"name": "roll_dice",
"description": "Roll a die with the given number of sides.",
"parameters": {
"type": "object",
"properties": {"sides": {"type": "integer"}},
"required": ["sides"],
},
},
}]
messages = [{"role": "user", "content": "Roll a twenty-sided die for me."}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
call = msg.tool_calls[0]
sides = json.loads(call.function.arguments)["sides"]
messages.append(msg)
messages.append({"role": "tool", "tool_call_id": call.id, "content": "14"})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)القيمة المعادة هنا ثابتة للاختصار. في الكود الحقيقي، اتصل بدالتك باستخدام sides وأرسل نتيجتها.
تفاصيل أكثر حول الأدوات. استخدم tool_choice عندما تحتاج إلى فرض دالة معينة بدلاً من ترك النموذج يقرر. واحتفظ بوصف الأدوات محدداً: يختار النموذج دالة من اسمها ووصفها فقط، لذا فإن "قم برمي نرد بعدد معين من الأوجه" يعمل بشكل أفضل من "نرد". إذا احتوى الرد على عدة استدعاءات أدوات، قم بتشغيلها جميعاً وأضف رسالة tool واحدة لكل معرف طلب قبل طلب الإجابة النهائية.
الأخطاء، إعادة المحاولة، وسجل المحادثة
يُطلق الـ SDK استثناءات محددة، مما يجعل معالجة الأخطاء مختصرة. يُطلق خطأ 429 openai.RateLimitError، وخطأ الشبكة يُطلق openai.APIConnectionError، وتطلق رموز الحالة الأخرى غير الناجحة openai.APIStatusError. يكون الـ SDK قد أعاد المحاولة بالفعل بحلول الوقت الذي ترى فيه الخطأ الأول، لذا فإن ما يصل إلى كودك هو استدعاء فشل مراراً وتكراراً.
import time
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY", max_retries=2)
def chat(messages, attempts=4):
delay = 2.0
for n in range(attempts):
try:
r = client.chat.completions.create(model="uncensored", messages=messages)
return r.choices[0].message.content
except openai.RateLimitError as e:
wait = float(e.response.headers.get("Retry-After", delay))
time.sleep(wait)
delay *= 2
except openai.APIConnectionError:
time.sleep(delay)
delay *= 2
raise RuntimeError("gave up after repeated failures")
print(chat([{"role": "user", "content": "Name a color."}]))يقرأ الكود رأس Retry-After عندما ترسله الخدمة، وهو ما يحدث عند الحمل الزائد المؤقت (القيمة 5 ثوانٍ). عندما يكون الرأس غائباً، يتبع استراتيجية التراجع حسب جدول زمني خاص به. لاحظ أن الحلقة لا تلتقط كل الأخطاء: لن يتحسن الطلب السيئ بإعادة المحاولة، لذا اتركه ينتشر.
سجل المحادثة هو جزء البيانات الآخر. لا تخزنه API لك، لذا يملك برنامجك قائمة الرسائل. سياسة بسيطة تعمل جيداً: احتفظ برسالة النظام، واحتفظ بآخر N من المشاركات، وعندما يتجاوز المجموع حجماً تختاره، اطلب من النموذج تلخيص الجزء الأقدم في رسالة قصيرة واحدة.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def compact(history, keep=6):
system, rest = history[0], history[1:]
if len(rest) <= keep:
return history
old, recent = rest[:-keep], rest[-keep:]
text = "\n".join(m["role"] + ": " + m["content"] for m in old)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Summarize this conversation in 120 words:\n" + text}],
max_tokens=250,
)
summary = {"role": "system", "content": "Earlier in this conversation: " + r.choices[0].message.content}
return [system, summary] + recentتكاليف الملخصات تشمل الرموز أيضاً، لكنها تبرر تكلفتها: محادثة كانت ستعيد إرسال 20,000 رمز في كل دور تنخفض إلى بضعة آلاف.
قراءة الرصيد ومعرف الطلب
يشمل كل استجابة X-Request-Id و X-Balance-USD. يخفي الـ SDK رؤوس HTTP افتراضياً، لكن with_raw_response يكشفها مع إبقاء الكائن المُحلل متاحاً لك.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say ok."}],
)
print("request id:", raw.headers.get("X-Request-Id"))
print("balance USD:", raw.headers.get("X-Balance-USD"))
completion = raw.parse()
print(completion.choices[0].message.content)سجّل معرف الطلب مع كل فشل. إذا احتجت إلى التواصل مع الفريق عبر صفحة الدعم، يشير هذا المعرف مباشرة إلى الاستدعاء.
يُعد رأس HTTP للرصيد مفيداً لأكثر من مجرد التسجيل. يمكن لوظيفة مجدولة قراءته بعد كل دفعة وإيقاف العملية عندما ينخفض الرصيد تحت عتبة تحددها، أو إرسال رسالة إليك لتتمكن من شحن الرصيد قبل أن يلاحظ المستخدمون ذلك. الرصيد لا ينتهي، لذا لا يوجد ضغط لإنفاقه. الشحنات تكون بمبالغ كاملة تتراوح بين $20 و$500، لذا يمكنك إعادة الشحن بخطوات أكبر إذا كنت تفضل ذلك.
بدون الـ SDK: requests أو httpx
إذا كنت تفضل تجنب الاعتمادية، فإن الـ API بسيط بما يكفي لعميل HTTP عادي.
import requests
r = requests.post(
"https://api.openaiapiproxy.com/v1/chat/completions",
headers={"Authorization": "Bearer YOUR_KEY"},
json={
"model": "uncensored",
"messages": [{"role": "user", "content": "Name three sea shanty topics."}],
},
timeout=120,
)
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])عيّن مهلة زمنية طويلة للإكمال الطويل. يمكن للنموذج استخدام قدر من نافذة الـ 100,000 رمز يتركه الموجّه فارغاً، لذا قد يستغرق الطلب غير المحدود للأدب القصصي الطويل وقتاً طويلاً.
نفس النهج يعمل مع البث المتدفق. أضف "stream": true إلى جسم JSON، ومرر stream=True إلى requests.post واقرأ الاستجابة باستخدام iter_lines(). يبدأ كل سطر حدث بـ data: متبوعاً بـ JSON، وينتهي البث بعلامة data: [DONE]. تحليل ذلك يدوياً هو تمرين تعليمي جيد، ولكن لكود الإنتاج، يقوم الـ SDK بذلك بعدد أقل من حالات الحافة، مثل الأسطر الجزئية وإعادة الاتصال.
إدارة الميزانية داخل كود Python
تتيح لك عدّ الرموز في resp.usage حساب الإنفاق لكل طلب. السعر هو $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج.
from openai import OpenAI
client = OpenAI(base_url="https://api.openaiapiproxy.com/v1", api_key="YOUR_KEY")
def cost_usd(prompt_tokens: int, completion_tokens: int) -> float:
return prompt_tokens * 0.15 / 1_000_000 + completion_tokens * 0.50 / 1_000_000
r = client.chat.completions.create(model="uncensored", messages=[{"role": "user", "content": "Hi"}])
print(cost_usd(r.usage.prompt_tokens, r.usage.completion_tokens))
print(cost_usd(1_000_000, 200_000)) # 0.25يتم التحقق من السطر الثاني يدوياً: تكلف مليون رمز مدخل $0.15 وتكلف 200,000 رمز مخرج 0.2 x $0.50 = $0.10، مما يجعل المجموع $0.25. الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها، لذا لا تحتاج إلى طرحها. تبدأ الشحنات من $20، وتُدرج صفحة الأسعار المكافآت عند $50 و$100 و$200.
لمزيد من التفاصيل حول قائمة المعاملات ورموز الأخطاء، راجع الوثائق.
احتفظ بمجموع متزايد في مهمتك حتى لا تنفق حلقة أكثر مما خططت له. تستخدم مهمة دفقية لتصنيف 50,000 نصاً قصيراً بـ 400 رمز مدخل و20 رمز مخرج لكل نص، ما مجموعه 20 مليون رمز مدخل و1 مليون رمز مخرج. يكلف ذلك 20 × $0.15 + 1 × $0.50 = $3.50. إذا أظهر عدادك أن المهمة تنفق ضعف ذلك، فهناك شيء يتكرر.
