مشاركة عبر

مرجع واجهة برمجة تطبيقات REST لنموذج الأساس

  • مقالة

توفر هذه المقالة معلومات واجهة برمجة التطبيقات العامة لواجهات برمجة تطبيقات نموذج Databricks Foundation والنماذج التي تدعمها. تم تصميم واجهات برمجة تطبيقات نموذج الأساس لتكون مشابهة لواجهة برمجة تطبيقات REST الخاصة ب OpenAI لتسهيل ترحيل المشاريع الحالية. تقبل كل من نقاط نهاية الدفع لكل رمز مميز ومعدل النقل المقدم نفس تنسيق طلب واجهة برمجة تطبيقات REST.

النهايه

يحتوي كل نموذج دفع لكل رمز مميز على نقطة نهاية واحدة، ويمكن للمستخدمين التفاعل مع نقاط النهاية هذه باستخدام طلبات HTTP POST. يمكن إنشاء نقاط نهاية معدل النقل المتوفرة باستخدام واجهة برمجة التطبيقات أو واجهة مستخدم الخدمة. تدعم نقاط النهاية هذه أيضا نماذج متعددة لكل نقطة نهاية لاختبار A/B، طالما أن كلا النموذجين المقدمين يعرضان نفس تنسيق واجهة برمجة التطبيقات. على سبيل المثال، كلا النموذجين هما نماذج دردشة.

تستخدم الطلبات والاستجابات JSON، تعتمد بنية JSON الدقيقة على نوع مهمة نقطة النهاية. تدعم نقاط نهاية الدردشة والإكمال استجابات الدفق.

تدعم أحمال عمل الدفع لكل رمز مميز نماذج معينة، راجع النماذج المدعومة للدفع لكل رمز مميز لتلك النماذج وتنسيقات واجهة برمجة التطبيقات المقبولة.

الاستخدام

تتضمن usage الاستجابات رسالة فرعية تبلغ عن عدد الرموز المميزة في الطلب والاستجابة. تنسيق هذه الرسالة الفرعية هو نفسه عبر جميع أنواع المهام.

الحقل نوع ‏‏الوصف
completion_tokens رقم صحيح عدد الرموز المميزة التي تم إنشاؤها. غير مضمن في تضمين الاستجابات.
prompt_tokens رقم صحيح عدد الرموز المميزة من موجه (مطالبات) الإدخال.
total_tokens رقم صحيح عدد الرموز المميزة الإجمالية.

بالنسبة لنماذج مثل llama-2-70b-chat مطالبة المستخدم يتم تحويلها باستخدام قالب مطالبة قبل تمريرها إلى النموذج. بالنسبة لنقاط نهاية الدفع لكل رمز مميز، قد تتم أيضا إضافة مطالبة النظام. prompt_tokens يتضمن كل النص الذي أضافه خادمنا.

مهمة الدردشة

تم تحسين مهام الدردشة لإجراء محادثات متعددة الأدوار مع نموذج. يصف كل طلب المحادثة حتى الآن، حيث messages يجب أن يتناوب الحقل بين user الأدوار و assistant ، وينتهي برسالة user . توفر استجابة النموذج الرسالة التالية assistant في المحادثة.

طلب الدردشة

الحقل Default النوع ‏‏الوصف
messages قائمة ChatMessage مطلوب. قائمة بالرسائل التي تمثل المحادثة الحالية.
max_tokens nil عدد صحيح أكبر من صفر أو nil، والذي يمثل اللانهاية الحد الأقصى لعدد الرموز المميزة التي يجب إنشاؤها.
stream true Boolean قم ببث الاستجابات مرة أخرى إلى عميل للسماح بنتائج جزئية للطلبات. إذا تم تضمين هذه المعلمة في الطلب، يتم إرسال الاستجابات باستخدام معيار الأحداث المرسلة من الخادم.
temperature 1.0 تعويم في [0,2] درجة حرارة أخذ العينات. 0 هي قيم حتمية والقيم الأعلى تقدم المزيد من العشوائية.
top_p 1.0 تعويم في (0,1] حد الاحتمال المستخدم لأخذ عينات النواة.
top_k nil عدد صحيح أكبر من صفر أو nil، والذي يمثل اللانهاية يحدد عدد الرموز المميزة k الأكثر احتمالا لاستخدامها لتصفية أعلى k. قم بتعيين هذه القيمة إلى 1 لجعل المخرجات محددة.
stop [] سلسلة أو قائمة[سلسلة] يتوقف النموذج عن إنشاء المزيد من الرموز المميزة عند مواجهة أي من التسلسلات في stop .
n 1 عدد صحيح أكبر من الصفر تقوم واجهة برمجة التطبيقات بإرجاع n إكمال الدردشة المستقلة عند n تحديدها. يوصى به لأحمال العمل التي تولد إكمالات متعددة على نفس الإدخال لتحقيق كفاءة استدلال إضافية وتوفير في التكاليف. متوفر فقط لنقاط نهاية معدل النقل المتوفرة.
tool_choice nil سلسلة أو ToolChoiceObject يستخدم فقط بالتزامن مع tools الحقل. tool_choice يدعم مجموعة متنوعة من سلاسل الكلمات الأساسية مثل autoو requiredو none. auto يعني أنك تسمح للنموذج بتحديد أي أداة (إن وجدت) ذات صلة للاستخدام. مع auto إذا كان النموذج لا يعتقد أن أيا من الأدوات في tools ذات الصلة، ينشئ النموذج رسالة مساعد قياسي بدلا من استدعاء أداة. required يعني أن النموذج يختار الأداة الأكثر صلة في tools ويجب أن ينشئ استدعاء أداة. none يعني أن النموذج لا ينشئ أي استدعاءات أداة وبدلا من ذلك يجب إنشاء رسالة مساعد قياسية. لفرض استدعاء أداة باستخدام أداة معينة محددة في tools، استخدم ToolChoiceObject. بشكل افتراضي، إذا تم tools tool_choice = "auto"ملء الحقل . وإلا، يتم tools تعيين الحقل افتراضيا إلى tool_choice = "none"
tools nil عنصر الأدوات قائمة tools يمكن للنموذج الاتصال بها. حاليا، function هو النوع الوحيد المدعوم tool ويتم دعم 32 وظيفة كحد أقصى.

ChatMessage

الحقل نوع الوصف
role السلسلة‬ مطلوب. دور كاتب الرسالة. يمكن أن يكون "system"أو "assistant" "user"أو ."tool"
content السلسلة‬ محتوى الرسالة. مطلوب لمهام الدردشة التي لا تتضمن استدعاءات الأدوات.
tool_calls قائمة "ToolCall" قائمة tool_calls التي أنشأها النموذج. يجب أن يكون لها role ك "assistant" ولا مواصفات للحقل content .
tool_call_id السلسلة‬ عندما role يكون هو "tool"، المعرف المقترن ToolCall بالرسالة التي تستجيب لها. يجب أن تكون فارغة للخيارات الأخرى role .

system يمكن استخدام الدور مرة واحدة فقط، كرسالة أولى في محادثة. يتجاوز مطالبة النظام الافتراضية للنموذج.

ToolCall

اقتراح إجراء استدعاء أداة من قبل النموذج. راجع استدعاء الدالة على Azure Databricks.

الحقل نوع الوصف
id السلسلة‬ مطلوب. معرف فريد لاقتراح استدعاء الأداة هذا.
type السلسلة‬ مطلوب. يتم دعم "function" فقط.
function FunctionCallCompletion مطلوب. استدعاء دالة يقترحه النموذج.

FunctionCallCompletion

الحقل نوع الوصف
name السلسلة‬ مطلوب اسم الدالة التي أوصى بها النموذج.
arguments ‏‏الكائن مطلوب. وسيطات للدالة كقاموس JSON متسلسل.

ToolChoiceObject

راجع استدعاء الدالة على Azure Databricks.

الحقل نوع الوصف
type السلسلة‬ مطلوب. نوع الأداة. حاليا، يتم دعم فقط "function" .
function ‏‏الكائن مطلوب. كائن يحدد الأداة التي يجب استدعاء النموذج {"type": "function", "function": {"name": "my_function"}} حيث "my_function هو اسم FunctionObject في tools الحقل.

ToolObject

راجع استدعاء الدالة على Azure Databricks.

الحقل نوع الوصف
type السلسلة‬ مطلوب. نوع الأداة. حاليا، يتم دعم فقط function .
function FunctionObject مطلوب. تعريف الدالة المقترنة بالأداة.

FunctionObject

الحقل نوع الوصف
name السلسلة‬ مطلوب. اسم الدالة التي سيتم استدعاؤها.
description ‏‏الكائن مطلوب. الوصف التفصيلي للدالة. يستخدم النموذج هذا الوصف لفهم صلة الدالة بالمطالبة وإنشاء استدعاءات الأداة بدقة أعلى.
parameters ‏‏الكائن المعلمات التي تقبلها الدالة، الموضحة كعنصر مخطط JSON صالح. إذا تم استدعاء الأداة، فإن استدعاء الأداة مناسب لمخطط JSON المقدم. يحدد حذف المعلمات دالة دون أي معلمات. يقتصر عدد properties المفاتيح على 15 مفتاحا.

استجابة الدردشة

بالنسبة للطلبات غير المتدفقة، تكون الاستجابة كائن إكمال دردشة واحد. بالنسبة لطلبات الدفق، تكون الاستجابة text/event-stream هي حيث يكون كل حدث كائن جزء إكمال. بنية المستوى الأعلى للإكمال والكائنات المكتملة متطابقة تقريبا: يحتوي فقط choices على نوع مختلف.

الحقل نوع الوصف
id السلسلة‬ معرف فريد لإكمال الدردشة.
choices List[ChatCompletionChoice] أو List[ChatCompletionChunk] (streaming) قائمة بنصوص إكمال الدردشة. n يتم إرجاع الخيارات إذا n تم تحديد المعلمة.
object السلسلة‬ نوع الكائن. يساوي إما "chat.completions" لعدم الدفق أو "chat.completion.chunk" للبث.
created رقم صحيح الوقت الذي تم فيه إنشاء إكمال الدردشة بالثوان.
model السلسلة‬ إصدار النموذج المستخدم لإنشاء الاستجابة.
usage الاستخدام بيانات تعريف استخدام الرمز المميز. قد لا يكون موجودا في استجابات الدفق.

ChatCompletionChoice

الحقل نوع ‏‏الوصف
index رقم صحيح فهرس الاختيار في قائمة الخيارات التي تم إنشاؤها.
message ChatMessage رسالة إكمال دردشة تم إرجاعها بواسطة النموذج. سيكون assistantالدور .
finish_reason السلسلة‬ سبب توقف النموذج عن إنشاء الرموز المميزة.

ChatCompletionChunk

الحقل نوع ‏‏الوصف
index رقم صحيح فهرس الاختيار في قائمة الخيارات التي تم إنشاؤها.
delta ChatMessage جزء رسالة إكمال الدردشة من الاستجابات المتدفقة التي تم إنشاؤها من النموذج. يتم ضمان role تعبئة المجموعة الأولى فقط.
finish_reason السلسلة‬ سبب توقف النموذج عن إنشاء الرموز المميزة. سيتم ملء هذه المجموعة الأخيرة فقط.

مهمة الإكمال

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

طلب الإكمال

الحقل Default النوع ‏‏الوصف
prompt سلسلة أو قائمة[سلسلة] مطلوب. المطالبة (المطالبات) للنموذج.
max_tokens nil عدد صحيح أكبر من صفر أو nil، والذي يمثل اللانهاية الحد الأقصى لعدد الرموز المميزة التي يجب إنشاؤها.
stream true Boolean قم ببث الاستجابات مرة أخرى إلى عميل للسماح بنتائج جزئية للطلبات. إذا تم تضمين هذه المعلمة في الطلب، يتم إرسال الاستجابات باستخدام معيار الأحداث المرسلة من الخادم.
temperature 1.0 تعويم في [0,2] درجة حرارة أخذ العينات. 0 هي قيم حتمية والقيم الأعلى تقدم المزيد من العشوائية.
top_p 1.0 تعويم في (0,1] حد الاحتمال المستخدم لأخذ عينات النواة.
top_k nil عدد صحيح أكبر من صفر أو nil، والذي يمثل اللانهاية يحدد عدد الرموز المميزة k الأكثر احتمالا لاستخدامها لتصفية أعلى k. قم بتعيين هذه القيمة إلى 1 لجعل المخرجات محددة.
error_behavior "error" "truncate" أو "error" للمهلات والأخطاء التي تم تجاوزها بطول السياق. أحد: "truncate" (إرجاع أكبر عدد ممكن من الرموز المميزة) و "error" (إرجاع خطأ). يتم قبول هذه المعلمة فقط عن طريق الدفع لكل نقاط نهاية الرمز المميز.
n 1 عدد صحيح أكبر من الصفر تقوم واجهة برمجة التطبيقات بإرجاع n إكمال الدردشة المستقلة عند n تحديدها. يوصى به لأحمال العمل التي تولد إكمالات متعددة على نفس الإدخال لتحقيق كفاءة استدلال إضافية وتوفير في التكاليف. متوفر فقط لنقاط نهاية معدل النقل المتوفرة.
stop [] سلسلة أو قائمة[سلسلة] يتوقف النموذج عن إنشاء المزيد من الرموز المميزة عند مواجهة أي من التسلسلات في stop .
suffix "" السلسلة‬ سلسلة ملحقة بنهاية كل اكتمال.
echo false Boolean إرجاع المطالبة مع الإكمال.
use_raw_prompt false Boolean إذا true، فمرر prompt مباشرة إلى النموذج دون أي تحويل.

استجابة الإكمال

الحقل نوع الوصف
id السلسلة‬ معرف فريد لإكمال النص.
choices إكمال التعليمات قائمة بإكمال النص. لكل مطالبة يتم تمريرها، n يتم إنشاء الخيارات إذا n تم تحديدها. الافتراضي n هو 1.
object السلسلة‬ نوع الكائن. يساوي "text_completion"
created رقم صحيح الوقت الذي تم فيه إنشاء الإكمال بالثوان.
usage الاستخدام بيانات تعريف استخدام الرمز المميز.

CompletionChoice

الحقل نوع ‏‏الوصف
index رقم صحيح فهرس المطالبة في الطلب.
text السلسلة‬ الإكمال الذي تم إنشاؤه.
finish_reason السلسلة‬ سبب توقف النموذج عن إنشاء الرموز المميزة.

مهمة التضمين

تعيين مهام تضمين سلاسل الإدخال في تضمين المتجهات. يمكن تجميع العديد من المدخلات معا في كل طلب.

تضمين الطلب

الحقل نوع ‏‏الوصف
input سلسلة أو قائمة[سلسلة] مطلوب. نص الإدخال المراد تضمينه. يمكن أن تكون سلسلة أو قائمة سلاسل.
instruction السلسلة‬ تعليمات اختيارية لتمريرها إلى نموذج التضمين.

التعليمات اختيارية ومحددة بشكل كبير. على سبيل المثال، لا يوصي مؤلفو BGE بأي إرشادات عند فهرسة المجموعات ويوصيون باستخدام التعليمات "Represent this sentence for searching relevant passages:" لاستعلامات الاسترداد. تدعم نماذج أخرى مثل Instructor-XL مجموعة واسعة من سلاسل التعليمات.

استجابة تضمينات

الحقل نوع الوصف
id السلسلة‬ معرف فريد للتضمين.
object السلسلة‬ نوع الكائن. "list"يساوي .
model السلسلة‬ اسم نموذج التضمين المستخدم لإنشاء التضمين.
data EmbeddingObject عنصر التضمين.
usage الاستخدام بيانات تعريف استخدام الرمز المميز.

EmbeddingObject

الحقل نوع الوصف
object السلسلة‬ نوع الكائن. "embedding"يساوي .
index رقم صحيح فهرس التضمين في قائمة التضمينات التي تم إنشاؤها بواسطة النموذج.
embedding List[Float] متجه التضمين. سيعيد كل نموذج متجه حجم ثابت (1024 ل BGE-Large)

الموارد الإضافية