انتقل إلى المحتوى
Sursa Developers

POST/v1/chat

بث إجابة المساعد (SSE)

chat

عند وجود عدة مثيلات من API خلف موازن أحمال (العنوان api.<domain>، الإصدار 1.62.0)، تعيش الإجابة ومخزن أحداثها المؤقت في ذاكرة المثيل الذي ينشئها. استئناف التدفق بالترويسة Last-Event-ID يعمل على ذلك المثيل فقط.

الطلب المكرر بالمعرّف request_id نفسه والمحادثة نفسها الذي يصل إلى مثيل آخر بعد انتهاء الإجابة يتلقى الإجابة المحفوظة (token وdone، والأحداث مرقّمة من 1) دون طرح السؤال من جديد. والطلب المكرر الذي يصل إلى مثيل آخر بينما لا تزال الإجابة قيد الإنشاء يوقف ذلك الإنشاء ويبني الإجابة من جديد؛ ولا يُنشأ سؤال ثانٍ في هذه الحالة أيضًا. لاستئناف التدفق دون إنشاء جديد، حافظ على الاتصال بالمثيل نفسه أو كرر الطلب بعد الحدث done.

المصادقة

أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.

معاملات الترويسة

  • X-View-Asstring

    لمفاتيح API ذات الدور admin فقط. ينفّذ الطلب بصفة ملف تعريف البيانات <profile>[:viewer|verifier|editor]، مثل employee:viewer. لا يمكن لمفتاح التثبيت استخدام هذه الترويسة (403).

معاملات ملفات تعريف الارتباط

  • kb_view_asstring

    ملف تعريف ارتباط وضع «View as» (عرض بصفة) للجلسة. تضبطه العملية POST /auth/view-as وتمسحه العملية DELETE /auth/view-as.

نص الطلب

application/json

الكائن: ChatRequest

  • messagesarray of ChatMessageمطلوب

    items ≥ 1

  • collectionstring

    القيمة الافتراضية: "default"

  • tagsarray of string | null
  • exportstring | null
  • card_idsarray of string | null

    items ≤ 50

  • streamboolean

    القيمة الافتراضية: false

  • conversation_idstring | null

    length ≤ 64

  • originstring | null
  • toolsboolean | null
  • bypass_cacheboolean

    عدم أخذ الإجابة من ذاكرة الإجابات المؤقتة (الزر «Get a fresh answer» (الحصول على إجابة جديدة) تحت الإجابة المخزنة مؤقتًا). تحل الإجابة الجديدة محل السجل المخزن مؤقتًا.

    القيمة الافتراضية: false

  • languagestring | null

    لغة الإجابة: رمز ISO 639-1 (de، en، ru، …) للإجابة بتلك اللغة. مع auto أو بلا الحقل، تُكتشف اللغة من السؤال. تمرّر الواجهة لغة الاقتراح المكتوب بلغة أخرى صراحةً (Starter.language).

  • scopeChatScope | null

    نطاق السؤال: عدة مجموعات، ومصدر، ووسوم، وفترة زمنية. تحل مجموعات النطاق محل collection. يحصر المصدر الإجابة في مجموعته (وفي بطاقاته). تُضاف الوسوم إلى tags. تحصر الفترة الإجابات المالية فيها. لا يمكنك اختيار إلا ما يراه المستخدم (المجموعات: collections.no_access/collections.not_found؛ المصدر: sources.not_found). مع conversation_id يُحفظ النطاق في المحادثة. بلا الحقل يُطبَّق نطاق المحادثة؛ والقيمة null أو النطاق الفارغ يمحوه.

  • request_idstring

    مفتاح عدم التكرار للسؤال. أرسل المفتاح نفسه في كل إعادة محاولة للتدفق الخاص بسؤال واحد (إعادة المحاولة بعد انقطاع الاتصال؛ وهنا لا تستأنف الترويسة Last-Event-ID التدفق بل تُسجَّل فقط). إعادة المحاولة بمفتاح إجابة محفوظة بالفعل لا تنشئ سؤالًا ثانيًا: تُرسَل النتيجة المحفوظة مرة أخرى في حدث done واحد (مع token بالنص)، حتى إن استُنفد حد الأسئلة أو الرصيد. وإذا كانت الإجابة السابقة لا تزال قيد الإعداد لعميل انقطع اتصاله، يتوقف إعدادها وتُعَدّ الإجابة من جديد.

    length ≤ 64

  • version_ofinteger (int64)

    ينشئ إصدارًا جديدًا من مداخلة هذا السؤال في المحادثة (question_id من سجل المحادثة): سؤال معدَّل (نص جديد في messages)، أو إجابة مُعادة الإعداد (النص نفسه، عادةً مع bypass_cache)، أو السؤال نفسه بقيمة أخرى للحقل quality (مثلًا precise بعد إجابة fast). يُحتفظ بزوج السؤال والإجابة السابق. تبقى المداخلات التي تليه في فرعه وتُخفى من سجل المحادثة ما دام الإصدار الجديد هو المختار (FeedItem.versions، POST /v1/conversations/{conv_id}/versions). السجل المستخدم للإجابة هو الفرع المختار حتى هذه المداخلة. لا تغيّر قيمة quality للإصدار إعدادات المحادثة. يتطلب conversation_id؛ والسؤال من محادثة أخرى يعيد 404 questions.not_found.

  • qualitystring

    الموازنة بين سرعة البحث الذي تقوم عليه النتيجة ودقته: fast أسرع، وprecise أدق. القيمة الافتراضية: precise.

    القيم المسموح بها: fastprecise

الاستجابات

200مع `stream=true`: النوع `text/event-stream`. يتكون كل حدث من السطرين `id: <number>` (الرقم التسلسلي للحدث في التدفق، بدءًا من 1) و`data: <JSON>`، يليهما سطر فارغ. لا يُستخدم الحقلان `event:` و`retry:`؛ ونوع الحدث في الحقل `type` (`ChatEvent`).

مع stream=true: النوع text/event-stream. يتكون كل حدث من السطرين id: <number> (الرقم التسلسلي للحدث في التدفق، بدءًا من 1) وdata: <JSON>، يليهما سطر فارغ. لا يُستخدم الحقلان event: وretry:؛ ونوع الحدث في الحقل type (ChatEvent).

يُجاب عن السؤال الذي له request_id بصرف النظر عن الاتصال. انقطاع الاتصال لا يوقف الإجابة: تُستكمل وتُحفظ في المحادثة (لمدة تصل إلى 10 دقائق). تكرار الطلب نفسه (المعرّف request_id نفسه والمحادثة نفسها) يرتبط بالإجابة الجارية، ومع الترويسة Last-Event-ID يتلقى الأحداث التي تلي ذلك الرقم، فيستمر التدفق بأرقام الأحداث نفسها. إذا تعذّر استمرار التدفق من ذلك الرقم، يحصل الطلب المكرر على التدفق من البداية: يكون رقم الحدث الأول عندئذٍ غير أكبر من Last-Event-ID، ويبدأ العميل الإجابة من جديد. إذا كانت الإجابة قد انتهت وحُرِّر مخزن أحداثها المؤقت (بعد 3 دقائق)، تُرسل النتيجة المحفوظة مرة أخرى (token وdone، مرقّمة من 1) دون طرح السؤال من جديد؛ وإلا تُنشأ الإجابة من جديد. لإيقاف مثل هذه الإجابة، استدعِ العملية POST /v1/chat/cancel. دون request_id، يُلغي انقطاع اتصال العميل الإجابة.

بعد الحدث الأول، وما دامت الإجابة جارية، يرسل الخادم التعليق : ping كل 15 ثانية؛ تجاهله. ترتيب الأحداث: أحداث stage (التقدّم)، ثم meta، وsources، وdata، ثم نص الإجابة في أحداث token، ثم done. قبل نص الإجابة، يمكن أن يتكرر sources وdata وأن تظهر أحداث tool؛ وقد يصل النص في حدث token واحد أو على أجزاء. الإجابة المخزَّنة مؤقتًا: meta (مع cached)، وsources، وdata، وtoken، وdone. الخطأ بعد بدء التدفق يصل في حدث error، ويُغلق التدفق دون done؛ وحالة HTTP للتدفق دائمًا 200. بعد done، قد يصل حدث followups بأسئلة تالية مقترحة. تجاهل أنواع الأحداث التي لا تعالجها.

مع stream=false: النوع application/json بنص AnswerResponse (إضافة إلى conversation_id).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

text/event-stream

الكائن: ChatEvent

واحد مما يلي

application/json

الكائن: AnswerResponse

  • answerstringمطلوب
  • question_idintegerمطلوب
  • querystring
  • collectionstringمطلوب
  • sourcesarray of Sourceمطلوب
  • table_queriesarray of TableQueryمطلوب
  • datasetsarray of Datasetمطلوب
  • chartsarray of ChartSpecمطلوب
  • warningsarray of AnswerWarningمطلوب
  • timingsTimingsمطلوب
  • provenancearray of NumberProvenance
  • emptystring

    القيم المسموح بها: no_hitsrestrictedguardrailno_data_for_period

  • basisAnswerBasis
  • verificationAnswerVerification
  • alt_periodsarray of AnswerAltPeriod

    items ≤ 6

  • drilldownarray of AnswerDrilldown

    items ≤ 20

  • restrictedRestrictedInfo
  • guardrailGuardrailVerdict
  • verified_onlyboolean
  • cachedboolean
  • cache_hitAnswerCacheHit
  • out_of_scopeAnswerOutOfScope
  • attachmentsarray of Attachment
  • export_errorstring
  • toolsstring | null

    لماذا استُخدمت الأدوات لهذه الإجابة: request (طُلبت صراحةً)؛ وcompare وcompute وaction (بناءً على السؤال)؛ وneeds_calc (يلزم حساب على الجداول)؛ وsummary (نظرة عامة على مجموعة أو مستندات)؛ وmcp (ربطت المؤسسة خوادم MCP خارجية).

    القيم المسموح بها: requestcomparecomputeactionneeds_calcsummarymcpnull

  • tool_callsarray of ToolCallInfo
  • calculationsarray of Calculation
  • pending_actionsarray of PendingAction
  • entitiesarray of AnswerEntityمطلوب
  • followupsarray of Followupمطلوب
  • conversation_idstring

    فقط للعملية POST /v1/chat مع محادثة.

  • answer_idstring

    معرّف كائن الإجابة.

400الطلب غير صالح: قيمة معامل أو حالة الكائن لا تسمح بالإجراء (الحقل `detail` رسالة نصية).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

401لم تُرسَل بيانات اعتماد (لا ملف تعريف ارتباط للجلسة ولا مفتاح API)، أو لم يُعثر على المفتاح.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

403الإجراء غير مسموح: الدور غير كافٍ، أو لا وصول إلى المجموعة أو البطاقة، أو يعمل الطلب في وضع «View as»، أو المؤسسة معلّقة أو محذوفة (الحقل `detail` كائن فيه `code: org_suspended | org_deleted`).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

404الكائن غير موجود أو غير متاح لك. لا تؤكد واجهة API وجود كائن مقيّد الوصول.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

422خطأ في صحة البيانات: نص الطلب أو المعاملات لا تطابق المخطط (الحقل `detail` قائمة بأخطاء صحة البيانات)، أو قيمة معامل خارج النطاق المسموح (الحقل `detail` رسالة نصية).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

429طلبات كثيرة جدًا (`api.rate_limited`)، أو استُنفدت حصة المؤسسة للدقيقة أو اليوم أو الشهر (`api.quota_exceeded`؛ يحتوي الحقل `error.details` على `quota` و`limit` و`reset_at`)، أو بلغت المؤسسة حدها، أو خدمة الإجابات مشغولة (`answers.engine_busy`). انتظر المدة المذكورة في الترويسة `Retry-After`.

ترويسات الاستجابة

  • Retry-After

    عدد الثواني التي تنتظرها قبل إعادة محاولة الطلب.

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: Error

رموز الأخطاء

الرموز التي قد تعيدها نقطة النهاية هذه في error.code، إضافةً إلى الرموز العامة لكل طلب.

إعادة المحاولة بأمان

أرسل الترويسة Idempotency-Key (قيمة UUID مثلًا) مع كل طلب POST وPATCH. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← answers · مرجع API