OpenAI Python SDK: التثبيت والإعداد والتكامل العملي

إن OpenAI Python SDK (الحزمة openai على PyPI) هو العميل الرسمي لـ Python لواجهة برمجة تطبيقات OpenAI. يتولى عمليات التوثيق، وتنسيق الطلبات، وتحليل الردود، والبث، وإعادة المحاولة. يغطي هذا الدليل التثبيت، والفئة الأساسية OpenAI، وإكمالات الدردشة، والبث، واستدعاء الدوال، والاستخدام غير المتزامن، وما يعادل JavaScript SDK، وتكامل Azure OpenAI، والتوافق مع Novita AI.

تثبيت حزمة OpenAI Python

مطلوب Python 3.10 أو إصدار أحدث:

pip install openai

إذا كنت مهاجرًا من واجهة برمجة التطبيقات القديمة 0.x، فاستبدل openai.ChatCompletion.create() بـ client.chat.completions.create().

قم بتعيين مفتاح API الخاص بك كمتغير بيئة. لا تضعه في كود المصدر:

export OPENAI_API_KEY="sk-..."

فئة عميل OpenAI

الفئة OpenAI هي نقطة الدخول الرئيسية. تقرأ مفتاح API من متغير البيئة OPENAI_API_KEY افتراضيًا، أو يمكنك تمريره صراحة:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
)

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

خيارات قابلة للتكوين عند التهيئة:

المعامل	الافتراضي	الوصف
api_key	متغير البيئة OPENAI_API_KEY	بيانات اعتماد المصادقة
base_url	https://api.openai.com/v1	تجاوز للوكيل أو واجهة برمجة تطبيقات متوافقة
timeout	600 ثانية	مهلة كل طلب
max_retries	2	إعادة المحاولة التلقائية عند أخطاء حد المعدل
http_client	None	عميل httpx مخصص لتكوين الوكيل أو الشهادة

إكمالات الدردشة: طلب أساسي

إكمالات الدردشة هي حالة الاستخدام الأكثر شيوعًا. تتبع قائمة messages نفس تنسيق واجهة برمجة التطبيقات: قائمة من القواميس (role/content) تمثل المحادثة:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "أنت مساعد برمجة مفيد."},
        {"role": "user", "content": "ما الفرق بين القائمة (list) و الصف (tuple) في بايثون؟"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

الرد هو كائن ChatCompletion. الحقول الرئيسية:

• response.choices[0].message.content — النص الرد
• response.usage.prompt_tokens — الرموز المميزة التي استهلكها الإدخال
• response.usage.completion_tokens — الرموز المميزة التي استهلكها الإخراج
• response.model — إصدار النموذج الذي خدم الطلب

للاستخدام الإنتاجي، مرر max_tokens لتجنب تكاليف التوليد الجامحة، و temperature=0 أو قيم منخفضة عندما تحتاج إلى مخرجات حتمية.

الردود البثية

للواجهات التفاعلية حيث يرى المستخدمون الرموز المميزة أثناء وصولها، استخدم stream=True:

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

with client.chat.completions.stream(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "اشرح مولدات بايثون بلغة بسيطة."},
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

يضمن استخدام مدير السياق (عبارة with) إغلاق الاتصال بشكل صحيح بعد التكرار. ينتج الخاصية .text_stream سلاسل نصية عادية؛ بينما ينتج .stream كائنات أحداث خام إذا كنت بحاجة إلى بيانات وصفية مثل إحصائيات الاستخدام لكل جزء.

إذا كنت بحاجة إلى البث بدون مدير السياق:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "اذكر 5 من أفضل ممارسات بايثون."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

استدعاء الدوال

يتيح استدعاء الدوال للنموذج تحديد متى يستدعي دالة وإرجاع كائن وسيطات JSON. ينفذ تطبيقك الدالة، ثم يرسل النتيجة مرة أخرى ليدمجها النموذج في رده:

import os
import json
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "إرجاع الطقس الحالي لمدينة.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "اسم المدينة، مثلاً 'سان فرانسيسكو'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "ما هو الطقس في طوكيو؟"}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls":
    tool_call = choice.message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    # نفذ وظيفتك الفعلية هنا
    result = {"city": args["city"], "temperature": "18°C", "condition": "غائم"}

    messages.append(choice.message)
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(result),
    })

    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    print(final.choices[0].message.content)

يعيد النموذج finish_reason="tool_calls" عندما يريد استدعاء دالة. تقوم بتشغيل الدالة، وإضافة النتيجة إلى قائمة الرسائل، وتقديم طلب ثانٍ. هذه الحلقة المكونة من خطوتين هي النمط القياسي.

الاستخدام غير المتزامن مع AsyncOpenAI

لـ FastAPI والخدمات المستندة إلى asyncio أو أي كود يستفيد من الإدخال/الإخراج غير المحظور، استخدم AsyncOpenAI:

import os
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

async def get_response(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256,
    )
    return response.choices[0].message.content

async def main():
    result = await get_response("ما هو asyncio في بايثون؟")
    print(result)

asyncio.run(main())

AsyncOpenAI هو نظير غير متزامن مباشر؛ جميع الطرق قابلة للانتظار. هذا أفضل من استخدام asyncio.to_thread لتغليف العميل المتزامن.

OpenAI JavaScript SDK

يشبه OpenAI JavaScript SDK (حزمة openai على npm) واجهة Python عن كثب. قم بتثبيته:

npm install openai

إكمال دردشة أساسي في Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "أنت مساعد مفيد." },
    { role: "user", content: "اشرح الفرق بين الـ promises و async/await في JavaScript." },
  ],
  max_tokens: 512,
});

console.log(response.choices[0].message.content);

البث في JavaScript:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const stream = await client.chat.completions.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "لخص واجهة fetch API في 3 جمل." }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content ?? "";
  process.stdout.write(text);
}

يدعم JavaScript SDK Node.js 18+ و Deno وبيئات المتصفح، لكن كشف مفتاح API الخاص بك في المتصفح غير آمن. استخدم وكيل جانب الخادم بدلاً من ذلك. يعمل خيار base_url لواجهات برمجة التطبيقات المتوافقة بنفس الطريقة كما في Python.

تكامل Azure OpenAI مع Python

إذا كنت تستخدم خدمة Azure OpenAI بدلاً من واجهة OpenAI المباشرة، فاستخدم عميل AzureOpenAI من نفس الحزمة:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

response = client.chat.completions.create(
    model="gpt-4o",  # اسم النشر الخاص بك في Azure
    messages=[
        {"role": "user", "content": "كيف يمكنني استخدام Azure OpenAI مع بايثون؟"},
    ],
)

print(response.choices[0].message.content)

متغيرات البيئة المطلوبة لـ Azure:

• AZURE_OPENAI_API_KEY: مفتاح API لمورد Azure الخاص بك
• AZURE_OPENAI_ENDPOINT: عنوان URL لنقطة النهاية الخاصة بك، مثلاً https://your-resource.openai.azure.com/

يشير المعامل model في Azure OpenAI إلى اسم النشر الخاص بك، وليس اسم النموذج الأساسي. قم بتعيين api_version لتتناسب مع إصدار واجهة برمجة تطبيقات Azure الذي يستخدمه النشر الخاص بك (راجع وثائق Azure OpenAI للحصول على الإصدارات المدعومة الحالية).

للمصادقة عبر Microsoft Entra ID (المعروف سابقًا بـ Azure AD) بدلاً من مفتاح API:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-02-01",
)

استخدام Novita AI مع نفس SDK

يكشف Novita AI عن نقطة نهاية متوافقة مع OpenAI على https://api.novita.ai/openai. يمكنك استخدام نفس openai Python أو JavaScript SDK وتغيير base_url و api_key فقط:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/openai",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v3.1",
    messages=[
        {"role": "system", "content": "أنت مساعد برمجة مفيد."},
        {"role": "user", "content": "اشرح كيف يؤثر GIL في بايثون على تعدد المهام."},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(response.choices[0].message.content)

احصل على مفتاح API لـ Novita AI من novita.ai/settings/key-management. يعمل نفس المفتاح عبر واجهات برمجة تطبيقات Novita AI، بما في ذلك نقطة النهاية المتوافقة مع OpenAI.

JavaScript مع Novita AI:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVITA_API_KEY,
  baseURL: "https://api.novita.ai/openai",
});

const response = await client.chat.completions.create({
  model: "qwen/qwen3-coder-480b-a35b-instruct",
  messages: [{ role: "user", content: "اكتب ورقة غش (cheatsheet) لتعليقات الأنواع في بايثون." }],
  max_tokens: 600,
});

console.log(response.choices[0].message.content);

كل شيء فيما بعد - البث، واستدعاء الدوال، والاستخدام غير المتزامن، و response_format، و temperature، و max_tokens - يعمل بنفس الطريقة.

متى تستخدم Novita Agent Sandbox

استخدم OpenAI SDK لاستدعاءات النموذج، ثم استخدم Novita Agent Sandbox عندما تحتاج سير العمل الخاص بك إلى تنفيذ كود، أو إجراءات متصفح، أو عمليات ملفات في عزلة. يحافظ ذلك على طبقة SDK مركزة على الاستدلال بينما يتعامل Sandbox مع الأجزاء الخطرة من حلقة الوكيل.

النماذج مفتوحة المصدر عبر Novita AI

يتيح لك تبديل base_url الوصول إلى نماذج الأوزان المفتوحة على Novita AI دون تغيير كود العميل الخاص بك. هذا مفيد عندما تريد نموذجًا للبرمجة، أو استخدام الأدوات، أو العمل ذي السياق الطويل، ولكنك لا تزال تريد نفس سير عمل SDK.

تنسيق معرف النموذج على Novita AI هو provider/model-name، ويمكنك تمريره مباشرة إلى المعامل model.

نمط توجيه مباشر للفرق التي ترغب في خلط النماذج المفتوحة والمغلقة:

def get_client(use_novita: bool = False) -> OpenAI:
    if use_novita:
        return OpenAI(
            api_key=os.environ["NOVITA_API_KEY"],
            base_url="https://api.novita.ai/openai",
        )
    return OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# استخدم الأوزان المفتوحة لمهام البرمجة الحساسة للتكلفة وعالية الحجم
coding_client = get_client(use_novita=True)

# استخدم OpenAI للمهام حيث يكون النموذج المغلق أفضل حقًا
openai_client = get_client(use_novita=False)

يتيح لك هذا اختبار A/B لجودة المخرجات، وتوجيه العمل إلى Novita AI عندما يكون مناسبًا، والحفاظ على مسار SDK واحد عبر المزودين.

الأسئلة الشائعة

ما اسم حزمة OpenAI Python؟

اسم الحزمة على PyPI هو openai. قم بالتثبيت باستخدام pip install openai.

ما اسم فئة عميل OpenAI في Python؟

الفئة الرئيسية هي OpenAI للاستخدام المتزامن و AsyncOpenAI للاستخدام غير المتزامن. كلاهما موجود في الوحدة openai: from openai import OpenAI, AsyncOpenAI.

هل يدعم OpenAI Python SDK البث؟

نعم. استخدم client.chat.completions.stream() كمدير سياق، أو مرر stream=True إلى client.chat.completions.create() وتكرار عبر الأجزاء.

ما اسم حزمة OpenAI JavaScript SDK؟

حزمة npm هي openai. قم بالتثبيت باستخدام npm install openai. توقيعات الفئة والطريقة متطابقة تقريبًا مع Python SDK.

كيف يمكنني استخدام Azure OpenAI مع Python؟

استخدم الفئة AzureOpenAI من حزمة openai. مرر azure_endpoint و api_key و api_version. يشير المعامل model إلى اسم النشر في Azure، وليس النموذج الأساسي.

هل يمكنني استخدام OpenAI Python SDK مع مزودين آخرين؟

نعم. يمكن استخدام أي مزود يطبق تنسيق واجهة Chat Completions من OpenAI عن طريق تعيين base_url على العميل. نقطة نهاية Novita AI على https://api.novita.ai/openai هي مثال واحد؛ مجموعة ميزات SDK الكاملة — البث، واستدعاء الدوال، وغير المتزامن — تعمل دون تغييرات.

كيف أحافظ على أمان مفتاح OpenAI API الخاص بي؟

قم بتخزين المفتاح في متغير بيئة (OPENAI_API_KEY) واقرأه باستخدام os.environ["OPENAI_API_KEY"]. لا تضعه أبدًا في كود المصدر، أو المستودعات العامة، أو سجلات البناء، أو JavaScript من جانب العميل.

مقالات موصى بها

• Novita AI تدعم الآن OpenAI Agents SDK! — قم بتوصيل نماذج Novita AI بـ OpenAI Agents SDK لتنسيق متعدد الوكلاء، والحواجز، والتتبع.
• بدء سريع مع Qwen3 Coder 30B A3B Instruct — معرف النموذج، والتسعير، ونافذة السياق، وأمثلة API لنموذج البرمجة الفعال من حيث التكلفة هذا على Novita AI.
• Vercel AI SDK: دليل مطور شامل لبناء تطبيقات الذكاء الاصطناعي — استخدم Vercel AI SDK مع نقطة نهاية Novita AI المتوافقة مع OpenAI للبث، واستدعاء الأدوات، وحلقات الوكيل في TypeScript.