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

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

تثبيت حزمة OpenAI Python

مطلوب Python 3.8 أو أحدث:

pip install openai

للتطوير، أضفها إلى requirements.txt أو pyproject.toml:

pip install openai>=1.0.0

الإصدار 1.x (الذي صدر في أواخر 2023) غيّر الواجهة بشكل كبير مقارنة بواجهة API 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	تجاوز للوكيل أو API متوافق
timeout	600 ثانية	المهلة الزمنية لكل طلب
max_retries	2	إعادة المحاولة التلقائية عند أخطاء حد المعدل
http_client	لا شيء	عميل httpx مخصص للوكيل أو تكوين الشهادة

إكمال المحادثات: طلب أساسي

إكمال المحادثات هو حالة الاستخدام الأكثر شيوعًا. قائمة messages تتبع نفس تنسيق API: قائمة من القواميس التي تحتوي على الدور والمحتوى وتمثل المحادثة:

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": "You are a helpful coding assistant."},
        {"role": "user", "content": "What is the difference between a list and a tuple in Python?"},
    ],
    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": "Explain Python generators in plain language."},
    ],
) 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": "List 5 Python best practices."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

استدعاء الدوال (Function Calling)

استدعاء الدوال يسمح للنموذج بتحديد متى يستدعي دالة وإرجاع كائن وسيط 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": "Returns current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'San Francisco'",
                    }
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

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)
    # Execute your actual function here
    result = {"city": args["city"], "temperature": "18°C", "condition": "cloudy"}

    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("What is asyncio in Python?")
    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: "You are a helpful assistant." },
    { role: "user", content: "Explain promises vs async/await in 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: "Summarize the fetch API in 3 sentences." }],
});

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",  # Your deployment name in Azure
    messages=[
        {"role": "user", "content": "How do I use Azure OpenAI with Python?"},
    ],
)

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 لتطابق إصدار API 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 المتوافقة مع OpenAI

تقدم 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-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Explain how Python's GIL affects multithreading."},
    ],
    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-30b-a3b-instruct",
  messages: [{ role: "user", content: "Write a Python type annotation cheatsheet." }],
  max_tokens: 600,
});

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

كل شيء في المصب — البث، استدعاء الدوال، الاستخدام غير المتزامن، response_format، temperature، max_tokens — يعمل بشكل متطابق. تتبع نقطة نهاية Novita AI مواصفات واجهة برمجة تطبيقات Chat Completions من OpenAI.

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

استبدال base_url يمنحك الوصول إلى كتالوج من النماذج مفتوحة الوزن التي أصبحت الآن تنافسية مع النماذج مغلقة المصدر في مهام محددة. بالنسبة لسير عمل الترميز، واستدعاء الدوال، والتفكير طويل السياق، ضاقت الفجوة العملية بشكل كبير.

النماذج المتاحة من خلال نقطة نهاية Novita AI المتوافقة مع OpenAI والتي تستحق التقييم:

DeepSeek V4 Pro (deepseek/deepseek-v4-pro): نموذج MoE كبير (ترخيص مشابه لـ MIT) يحتل مرتبة قريبة من القمة في معايير SWE-Bench ووظائف استدعاء الدوال. قوي لوكلاء الترميز، ومراجعة الكود، ومهام استخدام الأدوات متعددة الخطوات التي قد تستخدم فيها GPT-4o أو Claude Opus بدلاً من ذلك.

Qwen3 Coder 30B A3B Instruct (qwen/qwen3-coder-30b-a3b-instruct): نموذج MoE متناثر بحجم 30B من عائلة Qwen Coder، محسّن لتوليد الكود، وتصنيف الأخطاء، ومراجعة طلبات السحب. بسعر 0.07 دولار لكل مليون رمز إدخال و 0.27 دولار لكل مليون رمز إخراج على Novita AI، فهو أرخص بشكل كبير من معظم واجهات API المغلقة للمساعدة الروتينية في الترميز.

Qwen3 235B A22B Instruct (qwen/qwen3-235b-a22b-instruct-2507): نموذج MoE كبير (Apache 2.0) مع قدرات استدلال قوية وأداء ترميز متعدد اللغات. جيد للمهام التي تستخدم فيها حاليًا GPT-4o للاستجابات الإبداعية أو المعقدة ولكنك ترغب في تقليل التكلفة لكل رمز عند الحجم الكبير.

تنسيق معرف النموذج على 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"])

# Use open-weight for cost-sensitive, high-volume coding tasks
coding_client = get_client(use_novita=True)

# Use OpenAI for tasks where the closed model is genuinely better
openai_client = get_client(use_novita=False)

يتيح لك هذا اختبار جودة المخرجات بشكل A/B، وقياس أداء كل مهمة، وتحويل الحجم إلى نماذج أرخص دون لمس منطق الطلب.

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

ما هو اسم حزمة 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 هي مثال واحد؛ مجموعة الميزات الكاملة للحزمة — البث، استدعاء الدوال، غير المتزامن — تعمل دون تغييرات.

كيف أحافظ على أمان مفتاح 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.