لماذا يغطي واجهة برمجة التطبيقات (SDK) الخاصة بـ OpenAI ما تحتاجه
عندما يبحث الأشخاص عن qwen api sdk، فإنهم يريدون عادةً مكتبة عميل تتعامل مع المصادقة، إعادة المحاولة، البث المتدفق والاستجابات ذات الأنواع المحددة. حزم SDK الخاصة بـ OpenAI تقوم بكل ذلك بالفعل، وهذه الخدمة تطبق نفس واجهة HTTP: POST /v1/chat/completions، POST /v1/responses و GET /v1/models. أي عميل يتيح لك تجاوز عنوان URL الأساسي يمكنه التواصل معها.
توضيح واحد قبل البدء. هذه ليست الواجهة الرسمية لـ Alibaba أو لأي مزود نماذج آخر، وليست موزّعاً يعيد توجيه طلبك إلى مكان آخر. إنها نموذج مفتوح الأوزان واحد، تشغله جهة مستقلة ومضبوطة للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. معرف النموذج الوحيد الذي تمرره هو uncensored.
هذا يجعل الترحيل بسيطاً. إذا كان مشروعك يستدعي بالفعل نموذج دردشة مستضافاً عبر SDK لـ OpenAI، فإنك تغير ثلاث قيم: Base URL، مفتاح API واسم النموذج. لا يتعين نقل أي شيء آخر في الكود الخاص بك.
التثبيت وإجراء أول طلب
قم بتثبيت الحزمة الرسمية لـ Python أو Node. لا يوجد شيء خاص بالخدمة يجب إضافته.
pip install openai
# Node: npm install openai
أنشئ مفتاحًا على صفحة مفتاح API، ثم قم بتصديره بحيث لا يهبط أبدًا في كود المصدر الخاص بك.
export API_KEY="paste-your-key-here"
الآن أصغر سكربت Python مفيد. يقرأ العميل المفتاح من البيئة ويرسل الطلبات إلى الخدمة بدلاً من OpenAI.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what a context window is in two sentences."},
],
temperature=0.7,
)
print(resp.choices[0].message.content)
print(resp.usage)
إذا كنت تفضل HTTP الخام، فإن نفس الطلب في curl يبدو هكذا:
curl https://api.uncensoredqwen.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say hello."}]}'ردود البث المتدفق مع واجهة برمجة التطبيقات (SDK)
قم بتعيين stream=True وتكرار عبر القطع. ترسل الخدمة أحداثًا مرسلة من الخادم وتقارير استخدام الرموز في نهاية البث، لذا يمكنك تسجيل التكلفة دون الحاجة إلى مكالمة ثانية.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a desk lamp."}],
stream=True,
stream_options={"include_usage": True},
)
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):
print("\nTokens:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)
احتفظ بشيء واحد في الاعتبار: الطلب المتدفق يحتفظ بفتحة التزامن الخاصة به حتى ينتهي البث. إذا كان المستهلك بطيئًا أو نسيت إغلاق البث، فستصل إلى حد التزامن أسرع مما تتوقع.
نفس النمط في Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.uncensoredqwen.com/v1",
apiKey: process.env.API_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Name three uses of JSON mode." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}استدعاء الدوال ووضع JSON
معلمات واجهة برمجة التطبيقات (SDK) التي تستخدمها بالفعل للأدوات تمر مباشرة: tools، tool_choice، البث المتدفق tool_calls، والنتائج المرسلة مرة أخرى كرسائل مع role: "tool". تبدو رحلة الذهاب والعودة الدنيا هكذا:
import os, json
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up an order by id",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
messages.append(first.choices[0].message)
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps({"status": "shipped"}),
})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
للإخراج الهيكلي، مرر response_format={"type": "json_object"} وقل أيضًا "رد بصيغة JSON" في الموجّه. يطلب وضع JSON من النموذج إخراج JSON، ولكن يجب على الكود الخاص بك تحليله والتحقق من صحة أسماء الحقول والأنواع قبل استخدامها.
إعدادات أخذ العينات مثل temperature، top_p، stop، seed والعقوبات تمر عبرها، لذا فإن الضبط الحالي ينتقل.
معالجة أخطاء 429 وقراءة الرؤوس
تثير واجهة برمجة التطبيقات (SDK) استثناءً لحدّ المعدل على HTTP 429، ويخبرك جسم الاستجابة أي حد ضربته. يسمح المفتاح الكامل بـ 8 طلبات متزامنة و300 طلب في الدقيقة. يسمح مفتاح التجربة بـ 2 طلب متزامن و60 في الدقيقة.
| رمز الخطأ | المعنى | الإجراء المطلوب |
|---|---|---|
rate_limited | طلبات كثيرة جداً في الدقيقة | وزع المكالمات أو أضف مقيدًا من جانب العميل |
concurrency | عدد كبير من الطلبات في آن واحد | حدد الحد الأقصى لمجموعة العمال عند 8 (2 في مفتاح التجربة) |
429 مع Retry-After: 5 | حمل زائد مؤقت | انتظر 5 ثوانٍ وأعد المحاولة |
تحمل كل استجابة X-Request-Id، X-Balance-USD، X-RateLimit-Limit-Requests وX-RateLimit-Limit-Concurrency. لقراءتها باستخدام واجهة برمجة التطبيقات (SDK) الخاصة بـ Python، استخدم غلاف الاستجابة الخام:
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.uncensoredqwen.com/v1",
api_key=os.environ["API_KEY"])
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "ping"}],
max_tokens=5,
)
print("Balance:", raw.headers.get("X-Balance-USD"))
print("Request id:", raw.headers.get("X-Request-Id"))
completion = raw.parse()
الطلبات الفاشلة أو المرفوضة لا يتم شحنها، لذا فإن إعادة المحاولة بعد 429 لا تكلفك مرتين. يغطي المقال الموجود على أخطاء واجهة برمجة التطبيقات (API) الشائعة لـ Qwen المزيد من أخطاء الإعداد التي يواجهها الناس.
تكلفة الاستدعاء
التسعير هو $0.15 لكل مليون رمز (token) مدخل و$0.50 لكل مليون رمز (token) مخرج، يتم الدفع من رصيد مسبق الدفع. خذ طلبًا يحتوي على 2000 رمز (token) للموجه و500 رمز (token) للإكمال:
- الإدخال: 2,000 × $0.15 / 1,000,000 = $0.0003
- الإخراج: 500 × $0.50 / 1,000,000 = $0.00025
- المجموع: $0.00055
يغطي رصيد التجربة بقيمة $0.50 حوالي 900 طلب من هذا الحجم ($0.50 / $0.00055 يساوي تقريباً 909). التجربة هي نقرة واحدة على صفحة المفتاح بعد تسجيل الدخول، لا تحتاج إلى بطاقة وتنتهي بعد 7 أيام؛ يشرح مقال الطبقة المجانية كيفية عملها. تبدأ الشحنات المدفوعة من $20، وتذكر صفحة الأسعار مستويات المكافآت وطرق الدفع المقبولة.
السياق هو 100,000 رمز (token) للموجه والإكمال معًا، وmax_tokens اختياري. تعيينه لا يزال عادة جيدة عندما تريد حدًا علويًا متوقعًا للتكلفة.
نقل مشروع قائم
يصل معظم القراء بكود يتصل بالفعل بنموذج دردشة. قائمة تحقق قصيرة تبقي التبديل سلسًا:
- غيّر
base_url(أوbaseURLفي Node) إلىhttps://api.uncensoredqwen.com/v1. احتفظ بلاحقة/v1ولا تضف/chat/completionsبنفسك، لأن الـ SDK يضيف المسار. - استبدل المفتاح بالمفتاح الخاص بحسابك. المصادقة تتم عبر رأس
Authorization: Bearerالقياسي، الذي تبنيه المكتبة لك. - استبدل اسم النموذج بـ
uncensored. ستفشل الطلبات التي تحتوي على اسم نموذج غير معروف، لذا ابحث في شفرة المصدر الخاصة بك عن الأسماء الثابتة (hard-coded). - أزل أي حقول طلب للميزات التي لا تقدمها الخدمة، مثل إدخال الصور أو استدعاءات التضمين (embeddings).
- نفّذ استدعاءً لـ
GET /v1/modelsكاختبار دخاني (smoke test). إذا سردت النتيجة النموذج، فهذا يعني أن عنوان URL والمفتاح صحيحان.
تُعرِّض الأطر التي تغلف عميل OpenAI عادةً نفس الإعدادين الاثنين تحت أسماء مثل openai_api_base أو OPENAI_BASE_URL. إذا كانت أداتك توفر متغير بيئة لـ Base URL، يمكنك تبديل تطبيق كامل دون لمس الكود المصدري. اختبره بمفتاح تجريبي أولاً، لأن حدوده الأقل وهي 2 طلب متزامن و60 طلب في الدقيقة ستظهر بسرعة ما إذا كان تطبيقك يفتح اتصالات متزامنة أكثر مما خططت له.
تستحق معالجة السياق نظرة ثانية أيضاً. نافذة السياق هنا هي 100,000 رمز (token) مشتركة بين الموجّه (prompt) والإكمال (completion). إذا كان إعدادك القديم يقلل من حجم السجل التاريخي إلى حجم مختلف، يمكنك تخفيف أو تشديد ذلك التخفيض ليتطابق، لكن راقب تكلفة إعادة إرسال سجل طويل في كل دور.
نصائح عملية لشفرة الإنتاج
- أبقِ المفتاح خارج المستودع. اقرأه من متغير بيئة أو مخزن أسرار، كما في الأمثلة أعلاه.
- حدد مهلة زمنية (timeout). تقبل المكتبة وسيط
timeoutعند إنشاء العميل. تحتاج التوليدات الطويلة مع البث المتدفق (streaming) إلى مهلة قراءة سخية. - ربط عمالك. تجنب معظم أخطاء 429 قبل وقوعها باستخدام مجموعة خيوط (thread pool) أو إشارة (semaphore) بحجم يتوافق مع حدّ التزامن الخاص بك.
- سجّل معرف الطلب. إذا تواصلت مع الدعم، فإن القيمة من
X-Request-Idتحدد المكالمة. - راقب الرصيد. اقرأ
X-Balance-USDمن الاستجابات، أو قم باستدعاءGET /v1/balance، حتى تتوقف مهمة الدفعة قبل نفاد الرصيد.
النموذج يدعم النصوص فقط. لا يوجد توليد صور أو صوت أو فيديو، ولا تضمينات ولا ضبط دقيق، لذا لا تخطط حول طرق SDK تلك. التفاصيل الكاملة للمعاملات موجودة في التوثيق. لا تُستخدم الموجّهات للتدريب.
