دليل OpenAI Responses API: 14 مثالاً قابلاً للتشغيل لمطوري Python

دليل OpenAI Responses API: 14 مثالاً قابلاً للتشغيل لمطوري Python

الدليل الذي تحتاجه فعلاً لـ OpenAI Responses API: 14 مثالاً عملياً بلغة Python تغطي الأدوات المدمجة، والبث المباشر، واستدعاء الدوال، وMCP، والانتقال من Chat Completions في 3 خطوات. أُطلقت Responses API في 11 مارس 2025 بوصفها الأساس الموحّد لتطبيقات الوكلاء لدى OpenAI، وهي اعتباراً من أبريل 2026 نقطة البداية الموصى بها لكل مشروع OpenAI جديد. اختبرنا كل مثال وارد أدناه بالنسخة الأخيرة openai>=1.50 من Python SDK في أبريل 2026 — كل كتلة كود قابلة للتشغيل كما هي.

النقاط الرئيسية

• Responses API (أُطلقت في 11 مارس 2025) تجمع Chat Completions وAssistants وأدوات مدمجة في أداة واحدة ذات حالة.
• تدعم web_search وfile_search وcode_interpreter وcomputer_use وimage_generation وخوادم MCP البعيدة من الصندوق.
• الانتقال من Chat Completions يتمّ في 3 خطوات: تغيير النقطة النهائية، وإعادة تسمية messages إلى input، وتحديث مخططات الأدوات.
• استخدم previous_response_id مع store: true لإدارة الحالة الخفيفة؛ وConversations API للخيوط متعددة الدورات.

ما هي OpenAI Responses API؟

OpenAI Responses API أداة موحّدة أُطلقت في مارس 2025 تجمع بساطة Chat Completions مع قدرات استخدام الأدوات في Assistants API. وتدعم إدخال النصوص والصور، وأدوات مدمجة (البحث على الويب، والبحث في الملفات، ومترجم الكود، واستخدام الحاسوب، وتوليد الصور)، واستدعاء الدوال، والمخرجات المهيكلة، والبث المباشر، والمحادثات ذات الحالة عبر previous_response_id.

لماذا أطلقت OpenAI واجهة برمجة ثالثة وقد كانت Chat Completions تعمل بكفاءة؟ لأن حلقة الوكيل — النموذج يستدعي أداةً، يحصل على نتيجة، يقرر الخطوة التالية — كانت مرهقة البناء فوق chat.completions. كنت تجد نفسك تنقل نتائج الأدوات ذهاباً وإياباً داخل مصفوفات messages، أو تتصارع مع معرّفات الخيوط في Assistants API، أو تبني نظام حالة خاصاً من الصفر. تتعامل Responses API مع هذه الحلقة بوصفها مفهوماً أساسياً من الدرجة الأولى.

إن كنت تبدأ مشروع OpenAI جديداً عام 2026، فـ Responses API هي الخيار الافتراضي — وChat Completions هي الأداة القديمة التي تنتقل بعيداً عنها. الاستثناءات الكبرى: الصوت في الوقت الفعلي (استخدم Realtime API) والتضمينات النقية (استخدم Embeddings API). لكل شيء آخر — روبوتات الدردشة، والوكلاء، وأنابيب RAG، ومستخرجات البيانات المهيكلة — تشير وثائق OpenAI وإعلانها إلى Responses.

إن كنت تنسّق بين نماذج متعددة أو تريد طبقة هيكلية عالية المستوى، فعادةً ما تُقرن Responses API مع OpenAI Agents SDK. غطّينا المقارنة في مقالنا حول مقارنة OpenAI Agents SDK — خلاصته: Responses هي الأداة الأساسية، وAgents SDK هو الإطار.

كيف تختلف Responses API عن Chat Completions؟

Responses API مجموعة شاملة تضمّ Chat Completions: كل ميزة في Chat Completions تعمل في Responses، مضافاً إليها الأدوات المدمجة، وإدارة الحالة، وحلقة الوكيل. توصي OpenAI باستخدام Responses لجميع المشاريع الجديدة. تظل Chat Completions مدعومة لكنها لم تعد الأداة الأساسية الافتراضية للوكلاء.

إليك المقارنة التفصيلية، مستقاةً من وثائق منصة OpenAI:

كل ميزة في Chat Completions تعمل في Responses؛ والعكس ليس صحيحاً. قاعدة القرار مختصرة: إن كنت تحتاج أدوات مدمجة أو إدارة حالة أو تبدأ من جديد، استخدم Responses. أما إن كان لديك أنبوب Chat Completions مستقر لا يستخدم الأدوات وبوابتك لا تدعم Responses بعد، فالانتقال ليس ملحاً — فقط لا تبنِ وكلاء جديدة على الواجهة القديمة.

الإعداد وأول طلب مع Responses API

لإجراء أول طلب مع Responses API، ثبّت OpenAI Python SDK 1.50 أو أحدث، عيّن متغير البيئة OPENAI_API_KEY، ثم استدع client.responses.create() مع model وinput. المثال الكامل يستغرق أقل من 60 ثانية.

الخطوة 1 — تثبيت SDK:

pip install --upgrade "openai>=1.50"

الخطوة 2 — تعيين مفتاح API:

export OPENAI_API_KEY="sk-proj-..."

(في Windows PowerShell: $env:OPENAI_API_KEY = "sk-proj-...". لا تُدرجه في git أبداً — استخدم ملف .env مع python-dotenv للتطوير المحلي.)

الخطوة 3 — طلب تجريبي:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Say hello in exactly 5 words.",
)

print(response.output_text)

شغّل هذا وستحصل على تحية من خمس كلمات. المساعد output_text يجمع كل الأجزاء النصية في سلسلة واحدة — مفيد حين لا تهتم بالمخرج المهيكل.

الخطوة 4 — فحص كائن الاستجابة:

print("ID:        ", response.id)
print("Status:    ", response.status)
print("Model:     ", response.model)
print("Output:    ", response.output)            # list of output items
print("First text:", response.output[0].content[0].text)
print("Usage:     ", response.usage)             # input_tokens, output_tokens

مصفوفة response.output هي ما تحتاج حفظه. إنها قائمة من العناصر ذات الأنواع المكتوبة: نصوص، واستدعاءات أدوات، ونتائج أدوات، وملخصات التفكير. ستكرّر عليها باستمرار بمجرد أن تبدأ في استخدام الأدوات المدمجة.

كيف تبثّ الاستجابات مع Responses API؟

يعتمد البث في Responses API على Server-Sent Events. مرّر stream=True إلى client.responses.create() وكرّر على تدفق الأحداث الناتج. لكل حدث حقل type — response.output_text.delta لأجزاء الرموز وresponse.completed للحمولة النهائية. يوفر SDK 1.50+ تدفق أحداث مكتوب.

إن كنت تعرض الرموز على واجهة مستخدم، ستكرّر على أحداث response.output_text.delta وتتجاهل الباقي.

from openai import OpenAI

client = OpenAI()

with client.responses.stream(
    model="gpt-5",
    input="Write a haiku about Python decorators.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.error":
            print(f"\n[error] {event.error}")
            break
        elif event.type == "response.completed":
            print("\n[done]")

    final = stream.get_final_response()
    print(f"\nTokens: {final.usage.output_tokens}")

بعض ما اكتشفناه أثناء الاختبار: مدير سياق stream يتولى إغلاق الاتصال تلقائياً، لذا لا تُغلقه يدوياً. إن أردت البث غير المتزامن، استبدل OpenAI() بـ AsyncOpenAI() واستخدم async with مع async for — نفس أسماء الأحداث، نفس البنية.

الأدوات المدمجة: البحث على الويب، وبحث الملفات، ومترجم الكود، واستخدام الحاسوب، وتوليد الصور

تُشحن Responses API مع خمس أدوات مدمجة: web_search للبحث الحي على الإنترنت، وfile_search للاسترجاع من مخازن المتجهات، وcode_interpreter لتنفيذ Python في بيئة معزولة، وcomputer_use لأتمتة المتصفح وسطح المكتب، وimage_generation لإنشاء الصور مباشرة. فعّل أيًّا منها بإضافة {"type": "<tool_name>"} إلى مصفوفة tools.

إليك المصفوفة التي نبقيها مثبّتة بجانب المحرر:

حين اختبرنا web_search في أنبوبنا، أضافت 1.5–3 ثوانٍ في الطلب الأول لكنها تُخزَّن مؤقتاً للطلبات التالية — خطّط لذلك في واجهة المستخدم. يُعدّ مثال البحث على الويب في OpenAI Cookbook أوضح مرجع إن أردت التعمق أكثر.

البحث على الويب

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    tools=[{"type": "web_search"}],
    input="What did OpenAI announce at DevDay 2025? Cite your sources.",
)

print(response.output_text)

# Inspect the web_search_call items in response.output for raw search hits
for item in response.output:
    if item.type == "web_search_call":
        print(f"[searched] {item.query}")

بحث الملفات

بحث الملفات يتمّ على خطوتين: إنشاء مخزن متجهات، رفع ملفاتك، ثم الإشارة إلى معرّف المخزن في مصفوفة tools.

from openai import OpenAI

client = OpenAI()

# 1. Create a vector store + upload a file
store = client.vector_stores.create(name="company-handbook")
client.vector_stores.files.upload_and_poll(
    vector_store_id=store.id,
    file=open("handbook.pdf", "rb"),
)

# 2. Use it in a Responses call
response = client.responses.create(
    model="gpt-5",
    input="What's our PTO policy?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [store.id],
    }],
)
print(response.output_text)

مترجم الكود

تريد من النموذج تشغيل Python على ملف CSV ورسم شيء ما؟ يفعل code_interpreter ذلك في حاوية معزولة.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Read sales.csv and plot monthly revenue as a bar chart. Return a summary.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
)
print(response.output_text)

تستمر الحاوية بين الطلبات في نفس الجلسة — مفيد حين تريد من النموذج الاستمرار في العمل على إطار بيانات.

استخدام الحاسوب

لا تزال في مرحلة المعاينة حتى أبريل 2026. يحصل النموذج على متصفح/سطح مكتب افتراضي وينقر للقيام بمهام. تجنّبها ما لم يكن لديك حالة استخدام محددة لأتمتة المتصفح لا يمكن لـ Playwright/Selenium حلّها بالفعل.

توليد الصور

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Generate a diagram showing a CI/CD pipeline with build, test, and deploy stages.",
    tools=[{"type": "image_generation"}],
)

# Image bytes live in image_generation_call items
for item in response.output:
    if item.type == "image_generation_call":
        with open("pipeline.png", "wb") as f:
            f.write(item.result)

استدعاء الدوال مع الأدوات المخصصة

يُتيح استدعاء الدوال في Responses API للنموذج استدعاء دوال Python الخاصة بك. عرّف كل دالة كمخطط JSON في مصفوفة tools، نفّذ الطلب، تحقق من response.output لعناصر function_call، نفّذ الدالة، ومرّر النتيجة عبر function_call_output.

تحوّل Responses API استدعاء الدوال من رقصة أربع خطوات إلى رحلة واحدة حين تترك الحلقة الاستقلالية تتولى الأمر. إليك مثالاً كاملاً لتحويل العملات:

import json
from openai import OpenAI

client = OpenAI()

def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict:
    # Real impl would hit an FX API. Stubbed for the example.
    rate = 1.08 if (from_currency, to_currency) == ("USD", "EUR") else 1.0
    return {"amount": amount * rate, "currency": to_currency}

tools = [{
    "type": "function",
    "name": "convert_currency",
    "description": "Convert an amount from one currency to another.",
    "parameters": {
        "type": "object",
        "properties": {
            "amount": {"type": "number"},
            "from_currency": {"type": "string"},
            "to_currency": {"type": "string"},
        },
        "required": ["amount", "from_currency", "to_currency"],
    },
}]

# Turn 1: model decides to call our function
first = client.responses.create(
    model="gpt-5",
    input="How much is 250 USD in EUR?",
    tools=tools,
)

# Find the function_call item, run it, send the result back
for item in first.output:
    if item.type == "function_call" and item.name == "convert_currency":
        args = json.loads(item.arguments)
        result = convert_currency(**args)

        second = client.responses.create(
            model="gpt-5",
            previous_response_id=first.id,
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result),
            }],
            tools=tools,
        )
        print(second.output_text)

هذه الحلقة الكاملة. إن كنت جديداً على هذا النمط، يشرح مقالنا حول أساسيات استدعاء الدوال النموذج المفاهيمي، ولدينا أيضاً جولة على مكتبات استدعاء الدوال إن كنت تفضّل عدم كتابة المخططات يدوياً. معامل tool_choice (تعيينه إلى "auto" أو "required" أو اسم أداة محددة) هو رافعتك لإجبار أداة معيّنة أو حظرها حين تحتاج حتمية.

المخرجات المهيكلة (JSON Schema وPydantic)

المخرجات المهيكلة تضمن إعادة النموذج لـ JSON مطابق لمخططك. مرّر معامل response_format={"type": "json_schema", "json_schema": {...}} أو، مع Python SDK، ناوله نموذج Pydantic مباشرةً عبر client.responses.parse(). يُقيَّد النموذج عند وقت فك التشفير، لا بالتوجيه فحسب.

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Invoice(BaseModel):
    invoice_number: str
    total: float
    currency: str
    line_items: list[str]

response = client.responses.parse(
    model="gpt-5",
    input="Extract: Invoice #INV-2024-001 for $1,250.00 USD. Items: hosting, support, SSL cert.",
    text_format=Invoice,
)

invoice: Invoice = response.output_parsed
print(invoice.invoice_number, invoice.total, invoice.line_items)

مسار Pydantic هو الخيار الأمثل في 95% من الحالات — آمن من حيث الأنواع، أقل نماذجاً، ومحرّرك يكمل الكود تلقائياً. استخدم مخطط JSON الخام فقط حين تحتاج مشاركة المخططات عبر لغات أو حين يُولَّد المخطط ديناميكياً. نتعمق في المقارنة في دليلنا حول المخرجات المهيكلة ومخططات JSON ومقدمتنا حول Pydantic للمخططات الآمنة من حيث الأنواع.

إدارة الحالة: previous_response_id وConversations API وstore=true

استخدم previous_response_id للسياق الخفيف متعدد الدورات، وConversations API للجلسات ذات الخيوط المتينة، أو أرسل سجل الرسائل الكامل للتحكم الكامل من جانب العميل. previous_response_id تتطلب store: true ولا تستمر إلا للاستجابات المخزّنة مؤقتاً؛ ارجع إلى السجل الكامل إن كان المعرّف غير قابل للحل.

مثال على دورتين باستخدام previous_response_id:

from openai import OpenAI

client = OpenAI()

# Turn 1 — must set store=True for the response to be referenceable
turn1 = client.responses.create(
    model="gpt-5",
    input="My name is Mert and I'm building a weather agent.",
    store=True,
)

# Turn 2 — reference turn 1 by ID; the model "remembers" the name
turn2 = client.responses.create(
    model="gpt-5",
    previous_response_id=turn1.id,
    input="What was my name again?",
    store=True,
)

print(turn2.output_text)  # "Your name is Mert..."

إن نسيت store: true، فإن previous_response_id لن تحل إلى شيء والنموذج يبدأ من الصفر في كل دورة. أضعنا ساعة كاملة في تصحيح هذا — الواجهة لا تُعطي خطأ، بل تفقد الذاكرة بصمت. الاحتفاظ الافتراضي هو 30 يوماً؛ إن احتجت مدة أطول، انتقل إلى Conversations API التي توفر تحكماً صريحاً في دورة حياة الخيط.

متى تنتقل إلى Conversations API؟ حين يكون لديك مستخدمون متعددون في تطبيق واحد، حين تستمر الخيوط عبر جلسات، أو حين تريد تحرير الرسائل أو تفريعها من جانب الخادم. لروبوت دردشة سريع، يكفي previous_response_id تماماً.

كيف تنتقل من Chat Completions إلى Responses API؟

الانتقال من Chat Completions إلى Responses API يستغرق ثلاث خطوات: تغيير /v1/chat/completions إلى /v1/responses، استبدال messages بـ input، وتحديث مخططات الأدوات بالصيغة الجديدة. يحتاج استدعاء الدوال والإدخالات متعددة الوسائط معالجةً مختلفة قليلاً. تُوفّر OpenAI حزمة انتقال رسمية على GitHub.

الخطوة 1 — تبديل النقطة النهائية:

# Before (Chat Completions)
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Hello"}],
)
text = response.choices[0].message.content

# After (Responses)
response = client.responses.create(
    model="gpt-5",
    input="Hello",
)
text = response.output_text

الخطوة 2 — إعادة تسمية messages إلى input:

# Before
client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize this PDF."},
    ],
)

# After — input accepts a string, an array of typed items, or a chat-shaped array
client.responses.create(
    model="gpt-5",
    instructions="You are a helpful assistant.",   # system → instructions
    input="Summarize this PDF.",
)

الخطوة 3 — تحديث مخططات الأدوات:

# Before (Chat Completions tool format)
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
    },
}]

# After (Responses tool format — flatter, no nested "function" key)
tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get current weather",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}},
}]

هذا كل شيء. دحرج حركة المرور تدريجياً مع علامة ميزة — ابقِ مسار Chat Completions حياً خلف نفس الواجهة لأسبوع أو أسبوعين، سجّل شكلَي الاستجابة جنباً إلى جنب، واقلب إلى 100% فقط بعد التحقق من التكافؤ. تحتوي حزمة الانتقال على مستودع openai-cookbook على نمط مهيئ أكثر اكتمالاً إن أردت مرجعاً.

كيف تستخدم MCP وخوادم MCP البعيدة مع Responses API؟

تدعم Responses API خوادم MCP (بروتوكول سياق النموذج) البعيدة كنوع أداة. أضف إدخالاً كـ {"type": "mcp", "server_url": "https://mcp.example.com", "server_label": "..."} إلى مصفوفة tools. يكتشف النموذج كتالوج أدوات خادم MCP ويستدعيها مثل الأدوات المدمجة.

إن لم تتعامل مع MCP من قبل، إليك ملخص 30 ثانية: هو بروتوكول مفتوح يسمح لأي خدمة بكشف واجهة برمجتها كقائمة أدوات يمكن للنموذج استدعاؤها. تشغّل Shopify وStripe وGitHub وقائمة متنامية من البائعين نقاط نهاية MCP عامة. يغطي دليلنا حول بروتوكول سياق النموذج (MCP) البروتوكول نفسه بعمق.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Find me the top-ranking competitor for 'openai responses api tutorial' and summarize their content gaps.",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.semrush.com",
        "server_label": "semrush",
        "require_approval": "never",   # set to "always" in production
    }],
)
print(response.output_text)

عامل خوادم MCP كأي واجهة برمجة تابعة لجهة خارجية. require_approval: "never" مناسب للنماذج الأولية؛ في بيئة الإنتاج تريد "always" (أو قائمة بيضاء للأدوات) لمنع خادم MCP مخترق من تسريب البيانات بصمت. راجع كتالوج أدوات الخادم قبل توجيه وكيلك نحوه.

التسعير وحدود المعدلات ومخاطر الإنتاج

تسعير Responses API يطابق Chat Completions في تكاليف الرموز (المطالبة + الإكمال)، مع رسوم إضافية لكل طلب على الأدوات المدمجة (web_search، file_search). تتبع حدود المعدلات مستوى OpenAI الحالي الخاص بك. تشمل مخاطر الإنتاج الشائعة: الإعدادات الافتراضية للاحتفاظ في store: true، وأخطاء 429 العابرة في حركة المرور المتفجرة، وتأخر ميزات Azure.

الأسعار تتغير — تحقق دائماً من صفحة تسعير OpenAI عند الكتابة.

لمعالجة الأخطاء، غلّف الطلبات في try/except openai.RateLimitError وtry/except openai.APIStatusError، مع الإعادة بالتراجع الأسي عبر tenacity:

from openai import OpenAI, RateLimitError, APIStatusError
from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential

client = OpenAI()

@retry(
    retry=retry_if_exception_type((RateLimitError, APIStatusError)),
    wait=wait_exponential(multiplier=1, min=2, max=30),
    stop=stop_after_attempt(5),
    reraise=True,
)
def safe_create(prompt: str):
    return client.responses.create(model="gpt-5", input=prompt)

print(safe_create("Hello").output_text)

صادفنا خطأ 429 عابراً في دفعة من 20 طلباً متوازياً في بيئة التدريج لدينا — أصلحه tenacity مع التراجع الأسي بنظافة. نص الخطأ الذي سجّلناه كان openai.RateLimitError: Error code: 429 - {'error': {'message': 'Rate limit reached for gpt-5 in organization org-... on requests per min (RPM)'}}. اقرأه مرة واحدة وامضِ؛ مُزيّن retry يتولى الباقي.

ملاحظة حول Azure: تكشف Azure OpenAI عن Responses API لكنها تتأخر عن طرح OpenAI المباشر بـ 4–8 أسابيع. حتى أبريل 2026، دعم MCP على Azure في مرحلة معاينة فقط — تحقق من وثائق Azure OpenAI Responses API على Microsoft Learn قبل الإطلاق.

توافق البوابة: إن كنت تُوكّل OpenAI عبر LiteLLM proxy، دعم Responses API وصل في 2026. معظم البوابات الأخرى تتسارع للحاق. وللإطلاق في بيئة الإنتاج ستريد تشغيل مراقبة وتسجيل الذكاء الاصطناعي قبل تحويل حركة المرور — أحداث Responses API أكثر ثراءً من Chat Completions، وستريد تسجيل كل استدعاء أداة.

متى لا تستخدم Responses API؟

تجنّب Responses API في حالات الصوت في الوقت الفعلي منخفض الكمون (استخدم Realtime API)، وتوليد التضمينات (استخدم Embeddings API)، وسير عمل الضبط الدقيق. ابقَ على Chat Completions إن كانت بوابتك/وكيلك لا يدعم Responses بعد (معظمها يفعل عبر LiteLLM اعتباراً من 2026).

بعض حالات الاستبعاد الأمينة الإضافية:

• وكلاء الصوت في الوقت الفعلي — تستخدم Realtime API اتصالات WebSocket وصُمِّمت للتبادل بأقل من ثانية. بث Responses API هو HTTP SSE؛ سيبدو بطيئاً للصوت.
• أنابيب التضمينات النقية — client.embeddings.create() أرخص، أسرع، وما تتوقعه كل عملية تكامل مع قواعد بيانات المتجهات.
• الضبط الدقيق — تدرّب وتُطلق نماذج مضبوطة عبر fine-tuning API؛ يمكنك بعدها استدعاؤها عبر Responses، لكن التدريب نفسه ليس سير عمل Responses.
• مهام Batch API — إن كنت تعالج مليون مطالبة طوال الليل بخصم 50%، لا تزال Batch API تفوز في السعر.
• دلالات Chat Completions المقيّدة — إن كانت شبكة التقييم والمراقبة ومكتبة المطالبات تفترض chat.completions.choices[0].message.content، فتكلفة الانتقال حقيقية. لا تنتقل فقط لأنه أحدث.

إن كان مكدّسك مرتاحاً على Chat Completions ولا تبني وكلاء، الانتقال ليس مجانياً — ربط سباقك في Q2 قد لا يحتاجه. الأحدث لا يعني الأفضل لحالتك — Responses API هي الأداة المناسبة للوكلاء، لا لكل عبء عمل OpenAI.

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

ما هي OpenAI Responses API؟

OpenAI Responses API أداة موحّدة أُطلقت في مارس 2025 تجمع بساطة Chat Completions مع قدرات استخدام الأدوات في Assistants API. تدعم إدخال النصوص والصور، وخمس أدوات مدمجة، واستدعاء الدوال، والمخرجات المهيكلة، والبث المباشر، والمحادثات ذات الحالة عبر previous_response_id.

متى صدرت OpenAI Responses API؟

أعلنت OpenAI عن Responses API في 11 مارس 2025 ضمن إعلانها الأشمل "أدوات جديدة لبناء الوكلاء". الواجهة متاحة عموماً منذ الإطلاق، مع إضافة Conversations API ودعم MCP وأداة image_generation في تحديثات تدريجية طوال 2025 ومطلع 2026.

هل OpenAI Responses API ذات حالة؟

نعم — بشكل اختياري. مرّر previous_response_id مع store: true ويحمل النموذج السياق عبر الطلبات دون أن ترسل السجل الكامل. للخيوط الأطول عمراً، توفر Conversations API إدارة صريحة لدورة حياة الخيط. يمكنك أيضاً البقاء بلا حالة وإرسال السجل الكامل في كل دورة، مثل Chat Completions.

ما الفرق بين Responses API وChat Completions؟

Responses API مجموعة شاملة تضمّ Chat Completions. كل ميزة في Chat Completions تعمل في Responses، مضافاً إليها الأدوات المدمجة (web_search، file_search، إلخ)، وإدارة الحالة عبر previous_response_id، وحلقة الوكيل كمفهوم أساسي. توصي OpenAI باستخدام Responses لجميع المشاريع الجديدة اعتباراً من 2026.

هل Chat Completions API أُهملت؟

لا. حتى أبريل 2026، Chat Completions لم تُهمَل — لا تزال مدعومة بالكامل. توصي OpenAI بـ Responses للمشاريع الجديدة، ومعظم دروس الوكلاء تفترض Responses. Chat Completions الآن هي الأداة الإرثية: مستقرة، لكنها لم تعد المكان الذي تصل إليه الميزات الجديدة أولاً.

ما نماذج OpenAI التي تدعم Responses API؟

GPT-5 وgpt-5-mini وgpt-4.1 ونماذج الاستنتاج o-series تدعم Responses API جميعها. يضيف o-series معامل reasoning_effort (low، medium، high) لأعباء العمل ذات التفكير الممتد. يمر توليد الصور عبر gpt-image-1 داخلياً حين تفعّل أداة image_generation.

كيف أنتقل من Chat Completions إلى Responses API؟

ثلاث خطوات: بدّل client.chat.completions.create() إلى client.responses.create()، استبدل مصفوفة messages بـ input (وانقل مطالبات النظام إلى instructions)، واسطّح مخططات أدواتك (احذف المفتاح المتداخل function). تحتوي حزمة الانتقال من OpenAI على GitHub على أمثلة مهيّئات كاملة.

هل Responses API تدعم البث المباشر؟

نعم. مرّر stream=True إلى client.responses.create() (أو استخدم client.responses.stream() كمدير سياق) وكرّر على Server-Sent Events المكتوبة. أحداث تدفق الرموز التي ستتعامل معها هي response.output_text.delta للمحتوى وresponse.completed للحمولة النهائية. البث غير المتزامن يعمل عبر AsyncOpenAI.

هل يمكنني استخدام Responses API على Azure؟

نعم. تكشف Azure OpenAI عن Responses API، لكن تكافؤ الميزات يتأخر عن طرح OpenAI المباشر بـ 4–8 أسابيع. حتى أبريل 2026، دعم MCP على Azure في مرحلة معاينة. راجع Microsoft Learn للخصائص الحالية المتعلقة بـ Azure قبل الإطلاق في بيئة الإنتاج.

هل Responses API تعمل مع خوادم MCP؟

نعم — خوادم MCP البعيدة (بروتوكول سياق النموذج) نوع أداة من الدرجة الأولى. أضف {"type": "mcp", "server_url": "...", "server_label": "..."} إلى مصفوفة tools ويكتشف النموذج كتالوج أدوات الخادم ويستدعيها مثل أي أداة مدمجة. استخدم require_approval: "always" في بيئة الإنتاج للأمان.

خلاصة

حصلت الآن على الصورة الكاملة لـ Responses API: كيف تختلف عن Chat Completions، كيف تُطلق أول طلب، كيف توصّل الأدوات المدمجة، وكيف تنقل مشروع Chat Completions قائماً في ثلاث خطوات. بعض ما يستحق التذكّر:

• ابنِ أولاً، ثم حسّن. ابدأ بالمثال التجريبي، أضف أداة مدمجة، ثم طبّق إدارة الحالة مع previous_response_id.
• انتقل تدريجياً. استخدم علامة ميزة، سجّل شكلَي الاستجابة، اقلب إلى 100% فقط بعد التحقق من التكافؤ.
• أطلق تكاملات MCP. هذه هي حدود 2026 — معظم البائعين يتسابقون لكشف نقاط نهاية MCP، وResponses API هي الطريقة الأنظف لاستهلاكها.

في Techsy، نساعد الفرق على إطلاق تكاملات OpenAI على مستوى الإنتاج — بما فيها طرح Responses API والانتقال من Chat Completions. احصل على استشارة مجانية.

بقلم فريق Techsy التحريري — مهندسون إنتاج يُطلقون تكاملات OpenAI منذ 2024. آخر تحديث: 25 أبريل 2026.