AR ▾
احصل على مفتاح API
واجهة برمجة تطبيقات بدون رقابة متوافقة مع OpenAI للمطوّرين.تم التحديث

بث API المتوافق مع OpenAI في Python وNode

يعمل البث المتدفق عبر API المتوافق مع OpenAI هنا بنفس الطريقة عند الاتصال بـ OpenAI: اضبط stream: true، وجّه الـ SDK إلى base URL الخاص بنا، واقرأ أحداث SSE كما تصل. تحتوي هذه الصفحة على أكواد Python وNode.js عاملة، بالإضافة إلى ما يجب فعله عند انقطاع البث.

كتل متوهجة تتدفق واحدة تلو الأخرى من الخادم إلى جهاز لابتوب، توضح بث الرموز

ما يمنحك البث المتدفق

بدون البث المتدفق، تحتفظ واجهة برمجة التطبيقات بالرد الكامل حتى ينتهي النموذج من توليده، ثم ترسله كجسم JSON واحد. قد يعني الرد الطويل ذلك بقاء الشاشة فارغة لعدة ثوانٍ. مع stream: true، يرسل الخادم نفس الرد كسلسلة من الأحداث الصغيرة، يحمل كل منها بضع أحرف من الرد، ويمكن لواجهة المستخدم طباعتها فور وصولها.

صيغة الأسلاك هي أحداث مرسلة من الخادم (SSE) عبر استجابة HTTP عادية. كل حدث هو سطر يبدأ بـ data: متبوعًا بشريحة JSON، وينتهي البث بـ data: [DONE]. نادرًا ما تقوم بتحليل هذا يدويًا، لأن مكتبات OpenAI SDK تقوم بذلك نيابة عنك. إذا أردت رؤية البيانات الخام، يعرض ملف المطور العام تخطيط نقطة النهاية، ووثائق API تسرد كل معلمة.

هناك أمران يستحقان القرار قبل كتابة الكود. أولاً، من يقرأ التدفق: متصفح يتواصل مع خادمك، أم خادمك فقط؟ ثانياً، ماذا تفعل عندما ينقطع الاتصال في منتصف الطريق. يغطي باقي هذه الصفحة الأمرين.

Python: البث المتدفق باستخدام مكتبة OpenAI SDK

ثبّت المكتبة بـ pip install openai، أنشئ عميلاً باستخدام عنوان URL الأساسي الخاص بنا، ومرر stream=True. معرف النموذج هو uncensored.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.uncensoredllmapi.com/v1",
    api_key="YOUR_KEY",
)

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write a four-line poem about rain."}],
    stream=True,
)

text = []
usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        text.append(piece)
        print(piece, end="", flush=True)
    if getattr(chunk, "usage", None):
        usage = chunk.usage

print()
print("tokens:", usage)

انتبه للحاجز chunk.choices and .... القطعة النهائية التي تحمل بيانات الاستخدام قد تحتوي على قائمة choices فارغة، وقد يؤدي الوصول إليها بالفهرس إلى رفع خطأ. جمع القطع في قائمة ودمجها في النهاية أرخص من تكرار دمج السلاسل في الردود الطويلة.

Node: نفس الاستدعاء في JavaScript

مع الحزمة الرسمية openai لـ Node، تكون الدفقة مكررًا غير متزامن (async iterator). يستخدم هذا المثال وحدات ES.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.uncensoredllmapi.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Name three uses for a stream." }],
  stream: true,
});

let full = "";
let usage = null;
for await (const chunk of stream) {
  const piece = chunk.choices?.[0]?.delta?.content;
  if (piece) {
    full += piece;
    process.stdout.write(piece);
  }
  if (chunk.usage) usage = chunk.usage;
}
console.log("\nusage:", usage);

إذا لم ترد استخدام الـ SDK، فإن fetch يعمل أيضاً: أرسل نفس جسم الطلب بصيغة JSON مع stream: true، ثم اقرأ response.body باستخدام TextDecoder وقسم النص على الأسطر الفارغة. يوفر لك الـ SDK عناء معالجة الأحداث التي تُقطع عند حدود القطع، وهو الخطأ الشائع في المكتبات التي تُكتب يدوياً.

قراءة الاستخدام والرصيد

يتم الإبلاغ عن الاستخدام في نهاية الدفقة. هذا هو الرقم الذي يجب تسجيله لتتبع التكلفة، لأنه ما يُخصم من رصيدك. عند $0.15 لكل مليون رمز إدخال و$0.50 لكل مليون رمز إخراج، يكلف الرد الذي يحتوي على 1,200 رمز إدخال و800 رمز إخراج 1,200 x 0.15 / 1,000,000 + 800 x 0.50 / 1,000,000 = $0.00018 + $0.0004 = $0.00058.

يحمل كل استجابة أيضًا رأس X-Balance-USD مع رصيدك المتبقي، بحيث يمكنك عرض تحذيز انخفاض الرصيد دون طلب إضافي. يمكنك أيضًا استدعاء GET /v1/balance بشكل دوري. الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها، مما يعني أن الخطأ قبل ظهور الرمز الأول لا يكلف شيئًا.

تشمل رؤوس الاستجابة نفسها X-Request-Id. احفظه بجانب سطر السجل الخاص بك لكل دفقة. إذا تصرفت الدفقة بشكل غريب، فهذا هو المعرف الذي تقدمه للدعم ليتمكنوا من العثور على الطلب.

الدفقات المنقطعة وما يجب فعله حيالها

تنقطع الدفقات. قد يتحول الهاتف من الواي فاي إلى البيانات المتنقلة، أو يغلق الوكيل الاتصال الخامل، أو يغلق المستخدم علامة التبويب. خطط لذلك منذ البداية.

احتفظ بالنص الجزئي

أضف كل قطعة إلى المخزن المؤقت عند وصولها، واحفظ المخزن المؤقت عند انتهاء الحلقة أو حدوث خطأ. إذا فشلت الدفقة، سيكون لديك رد نصف جاهز صالح للاستخدام. اعرضه مع زر إعادة المحاولة بدلاً من تجاهله.

إعادة المحاولة أو الاستمرار

أبسط استعادة هي إعادة إرسال الطلب الأصلي. بالنسبة لرد قصير، فهذا كافٍ. بالنسبة لرد طويل، يمكنك إرسال النص الجزئي المحفوظ كرسالة مساعد وطلب من النموذج الاستمرار من حيث توقف. قد لا يتطابق الناتج مع ما كان سيُنتجه البث الأول، لذا عامله كجهد أفضل وسمّهِ في واجهة المستخدم إذا كانت الدقة مهمة.

أغلق ما تتخلى عنه

الطلب المتدفق يشغل فتحة التزامن الخاصة به حتى ينتهي البث. المفتاح الكامل يسمح بـ 8 طلبات في وقت واحد، والمفتاح التجريبي يسمح بـ 2 فقط. إذا كان خادمك يستمر في قراءة بث لمستخدم غادر، تظل هذه الفتحة مشغولة. ألغِ الطلب عند قطع اتصال العميل. في Python، استدعِ stream.close()؛ في Node، استدعِ stream.controller.abort().

إعادة بث البث إلى المتصفح

لا تضع مفتاح API الخاص بك في كود المتصفح. الإعداد المعتاد هو نقطة نهاية صغيرة على خادمك الخاص تستدعي الـ API مع stream: true وتتمرير كل قطعة إلى الصفحة. في Node.js مع Express، اضبط Content-Type: text/event-stream، واكتب كل قطعة بصيغة data: ... متبوعة بسطر فارغ، واستمع لحدث close على الطلب لإلغاء استدعاء الخادم البعيد. في الصفحة، يتعامل EventSource مع نقاط النهاية التي تستخدم GET، بينما يتعامل fetch مع القارئ مع أجوبة POST، وهو ما تحتاجه عند إرسال سجل الرسائل.

احتفظ بسجل الرسائل على خادمك أو في جسم الطلب، وقص الدور الأقدم عندما يصبح المحادثة طويلة. نافذة السياق هي 100,000 رمز للموجّه بالإضافة إلى الإكمال، وهو الكثير من الدردشة، لكن الجلسة طويلة الأمد ستصل إليها في النهاية.

حدود المعدل أثناء البث

الحدود هي 300 طلب في الدقيقة و8 طلبات متزامنة على المفتاح الكامل، و60 في الدقيقة و2 متزامن على المفتاح التجريبي. تجاوز الحدود يعيد HTTP 429. رمز الخطأ يخبرك أي حد ضربته: rate_limited يعني طلبات كثيرة جداً في الدقيقة، وconcurrency يعني طلبات كثيرة جداً في وقت واحد. في حالة الحمل الزائد المؤقت، تعيد الـ API أيضاً 429 مع رأس Retry-After: 5.

بما أن 429 يصل قبل أن يتم بث أي رموز، تعامل معه قبل أن تبدأ القراءة. غلاف إعادة المحاولة الصغير كافٍ:

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.uncensoredllmapi.com/v1", api_key="YOUR_KEY")

def open_stream(messages, tries=4):
    for n in range(tries):
        try:
            return client.chat.completions.create(
                model="uncensored", messages=messages, stream=True
            )
        except RateLimitError as e:
            wait = 5 if n == 0 else 5 * (n + 1)
            time.sleep(wait)
    raise RuntimeError("still rate limited")

لتطبيقات الدردشة مع العديد من المستخدمين، الإصلاح الحقيقي لأخطاء concurrency هو طابور صغير من جانبك يسمح بأقصى 8 بثات حية في وقت واحد.

قائمة التحقق قبل إطلاق دردشة متدفقة

  • احذر من choices الفارغة في الشريحة الأخيرة.
  • تخزين النص الجزئي وحفظه عند الخطأ.
  • أبطل طلب الخادم المصدر عند قطع اتصال المتصفح.
  • حصر البثات الحية عند حد التزامن الخاص بك.
  • تسجيل الاستخدام ورمز الطلب لكل تدفق.
  • إيقاف تخزين الاستجابة على أي وكيل عكسي أمام خادمك، أو ستصل الرموز على دفعات.

تُربك النقطة الأخيرة العديد من عمليات النشر الأولية. يقوم Nginx، على سبيل المثال، بتخزين استجابات الوسيط افتراضيًا، لذا يعمل البث المتدفق على localhost ويبدو متجمدًا في بيئة الإنتاج حتى يتم تعطيل التخزين المؤقت لذلك المسار. للإخراج بصيغة JSON بدلاً من النص الحر، انظر إلى ملاحظات وضع JSON. لتجربة الكود أعلاه، أنشئ مفتاح API؛ يمكن للحسابات الجديدة المطالبة بـ $0.50 من رصيد تجريبي مجاني بنقرة واحدة، صالح لمدة 7 أيام. الشحنات تكون بالعملات المشفرة فقط (USDT على TRC20 أو USDC على Base)، من $20.

أسئلة وأجوبة

هل أحتاج إلى SDK خاص للبث المتدفق؟

لا. حزم Python وNode القياسية لـ OpenAI تعمل. غيّر base URL، والمفتاح واسم النموذج إلى uncensored، ثم مرر stream: true.

هل يمكنني بث استدعاء الدوال ووضع JSON؟

نعم بالنسبة لاستدعاء الدوال: يتم بثها كقطع deltas من tool_calls، وتجمع القطع قبل تحليل الحجج. اختبر أي بث في وضع JSON بنفس الطريقة، بتحليل البيانات فقط بعد آخر قطعة.

هل أُحسب مقابل البث الذي ألغيه؟

الطلبات الفاشلة أو المرفوضة لا تُحاسب عليها. للبث الذي تلغيه في منتصف الطريق، تحقق من قيم الاستخدام وX-Balance-USD في سجلاتك الخاصة لمعرفة ما تم احتسابه.

لماذا يصل البث المتدفق دفعة واحدة؟

من المحتمل أن يكون وسيط أو شبكة توصيل المحتوى (CDN) أمام تطبيقك يقوم بتخزين الاستجابة مؤقتًا. قم بإيقاف التخزين المؤقت لمسار البث المتدفق ثم تحقق مرة أخرى.

مفتاحك على بُعد نموذج تعبئة واحد

أنشئ حساباً، وانسخ المفتاح، ثم غيّر base URL. هذا هو الإعداد الكامل.