مشاركة عبر

مرجع واجهة برمجة تطبيقات المساعدين (معاينة)

  • مقالة

إشعار

  • يمكن للبحث عن الملفات استيعاب ما يصل إلى 10000 ملف لكل مساعد - 500 مرة أكثر من ذي قبل. وهو سريع، ويدعم الاستعلامات المتوازية من خلال عمليات البحث متعددة مؤشرات الترابط، وميزات محسنة لإعادة الإرسال وإعادة كتابة الاستعلام.
    • مخزن المتجهات هو كائن جديد في واجهة برمجة التطبيقات. بمجرد إضافة ملف إلى مخزن متجهات، يتم تحليله تلقائيا، وتقسيمه، ودمجه، ويكون جاهزا للبحث فيه. يمكن استخدام مخازن المتجهات عبر المساعدين ومؤشرات الترابط، مما يبسط إدارة الملفات والفوترة.
  • لقد أضفنا دعما للمعلمة tool_choice التي يمكن استخدامها لفرض استخدام أداة معينة (مثل البحث في الملفات أو مترجم التعليمات البرمجية أو وظيفة) في تشغيل معين.

توفر هذه المقالة وثائق مرجعية ل Python وREST لواجهة برمجة تطبيقات المساعدين الجديدة (معاينة). يتم توفير إرشادات أكثر تعمقا خطوة بخطوة في دليل البدء.

إنشاء مساعد

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

إنشاء مساعد باستخدام نموذج وتعليمات.

نص الطلب

Name نوع مطلوبة ‏‏الوصف
نموذج سلسلة المطلوب اسم نشر النموذج للنموذج المراد استخدامه.
الاسم سلسلة أو قيمة خالية اختياري اسم المساعد. الحد الأقصى للطول هو 256 حرفا.
الوصف سلسلة أو قيمة خالية اختياري وصف المساعد. الحد الأقصى للطول هو 512 حرفا.
التوجيهات سلسلة أو قيمة خالية اختياري إرشادات النظام التي يستخدمها المساعد. الحد الأقصى للطول هو 256000 حرف.
الأدوات صفيف اختياري الإعدادات الافتراضية إلى []. قائمة بالأدوات الممكنة على المساعد. يمكن أن يكون هناك 128 أداة كحد أقصى لكل مساعد. يمكن أن تكون الأدوات حاليا من أنواع code_interpreterأو function. function يمكن أن يكون الوصف بحد أقصى 1024 حرفا.
file_ids صفيف اختياري الإعدادات الافتراضية إلى []. قائمة بمعرفات الملفات المرفقة بهذا المساعد. يمكن أن يكون هناك بحد أقصى 20 ملفا مرفقا بالمساعد. يتم ترتيب الملفات حسب تاريخ إنشائها بترتيب تصاعدي.
بيانات التعريف map اختياري مجموعة من 16 زوجا من قيم المفاتيح التي يمكن إرفاقها بعنصر. يمكن أن يكون هذا مفيدا لتخزين معلومات إضافية حول الكائن بتنسيق منظم. يمكن أن يكون طول المفاتيح 64 حرفا كحد أقصى ويمكن أن تكون القيم بحد أقصى 512 حرفا.
درجة الحرارة رقم أو قيمة خالية اختياري تعود الإعدادات الافتراضية على 1. تحديد درجة حرارة أخذ العينات التي يجب استخدامها، بين 0 و2. القيم الأعلى مثل 0.8 ستجعل الإخراج أكثر عشوائية، بينما القيم الأقل مثل 0.2 ستجعله أكثر تركيزا وحسما.
top_p رقم أو قيمة خالية اختياري تعود الإعدادات الافتراضية على 1. بديل لأخذ العينات مع درجة الحرارة، يسمى أخذ عينات النواة، حيث يأخذ النموذج في الاعتبار نتائج الرموز المميزة مع كتلة الاحتمال top_p. لذا فإن 0.1 يعني أن الرموز المميزة التي تشكل كتلة الاحتمال الأعلى بنسبة 10٪ هي التي تعتبر فحسب. نوصي عمومًا بتغيير هذا أو درجة الحرارة، ولكن ليس كليهما.
response_format سلسلة أو عنصر اختياري تحديد التنسيق الذي يجب على النموذج إخراجه. متوافق مع GPT-4 Turbo وجميع طرز GPT-3.5 Turbo منذ gpt-3.5-turbo-1106. تعيين هذه المعلمة لتمكين { "type": "json_object" } وضع JSON، والذي يضمن الرسالة التي ينشئها النموذج هي JSON صالحة. والأهم من ذلك، عند استخدام وضع JSON، يجب عليك أيضا إرشاد النموذج لإنتاج JSON بنفسك باستخدام نظام أو رسالة مستخدم. بدون هذه التعليمات، قد ينشئ النموذج دفقا لا ينتهي من المسافة البيضاء حتى يصل الجيل إلى حد الرمز المميز، ما يؤدي إلى طلب طويل الأمد ويبدو أنه "عالق". بالإضافة إلى ذلك، قد يتم قطع محتوى الرسالة جزئيا إذا كنت تستخدم finish_reason="length"، مما يشير إلى تجاوز max_tokens الجيل أو تجاوز المحادثة الحد الأقصى لطول السياق.

المرتجعات

كائن مساعد .

مثال على إنشاء طلب مساعد

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

إنشاء ملف مساعد

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview

إنشاء ملف مساعد عن طريق إرفاق File ب assistant.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي يجب إرفاق الملف به.

نص الطلب

Name نوع مطلوبة ‏‏الوصف
file_id سلسلة المطلوب معرف ملف (مع الغرض ="المساعدين") الذي يجب أن يستخدمه المساعد. مفيد لأدوات مثل code_interpreter التي يمكنها الوصول إلى الملفات.

المرتجعات

كائن ملف مساعد.

مثال إنشاء طلب ملف مساعد

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

مساعدو القائمة

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

إرجاع قائمة بجميع المساعدين.

معلمات الاستعلام

المعلمة نوع مطلوبة ‏‏الوصف
limit integer اختياري حد لعدد العناصر التي سيتم إرجاعها. يمكن أن يتراوح الحد بين 1 و100، والافتراضي هو 20.
order سلسلة اختياري - الإعدادات الافتراضية ل desc ترتيب الفرز حسب الطابع الزمني created_at للكائنات. asc للترتيب التصاعدي و desc للترتيب التنازلي.
after سلسلة اختياري مؤشر للاستخدام في ترقيم الصفحات. after هو معرف كائن يحدد مكانك في القائمة. على سبيل المثال، إذا قمت بإجراء طلب قائمة وتلقيت 100 عنصر، تنتهي obj_foo، يمكن أن تتضمن المكالمة اللاحقة بعد =obj_foo لإحضار الصفحة التالية من القائمة.
before سلسلة اختياري مؤشر للاستخدام في ترقيم الصفحات. before هو معرف كائن يحدد مكانك في القائمة. على سبيل المثال، إذا قمت بإجراء طلب قائمة وتلقيت 100 عنصر، تنتهي obj_foo، يمكن أن تتضمن المكالمة اللاحقة قبل=obj_foo لإحضار الصفحة السابقة من القائمة.

المرتجعات

قائمة بعناصر المساعد

أمثلة على مساعدي القائمة

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

سرد ملفات المساعد

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview

إرجاع قائمة بملفات المساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي ينتمي إليه الملف.

معلمات الاستعلام

المعلمة نوع مطلوبة ‏‏الوصف
limit integer اختياري حد لعدد العناصر التي سيتم إرجاعها. يمكن أن يتراوح الحد بين 1 و100، والافتراضي هو 20.
order سلسلة اختياري - الإعدادات الافتراضية ل desc ترتيب الفرز حسب الطابع الزمني created_at للكائنات. asc للترتيب التصاعدي و desc للترتيب التنازلي.
after سلسلة اختياري مؤشر للاستخدام في ترقيم الصفحات. after هو معرف كائن يحدد مكانك في القائمة. على سبيل المثال، إذا قمت بإجراء طلب قائمة وتلقيت 100 عنصر، تنتهي obj_foo، يمكن أن تتضمن المكالمة اللاحقة بعد =obj_foo لإحضار الصفحة التالية من القائمة.
before سلسلة اختياري مؤشر للاستخدام في ترقيم الصفحات. before هو معرف كائن يحدد مكانك في القائمة. على سبيل المثال، إذا قمت بإجراء طلب قائمة وتلقيت 100 عنصر، تنتهي obj_foo، يمكن أن تتضمن المكالمة اللاحقة قبل=obj_foo لإحضار الصفحة السابقة من القائمة.

المرتجعات

قائمة بعناصر ملفات المساعد

مثال على ملفات مساعد القائمة

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

استرداد مساعد

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

استرداد مساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد المراد استرداده.

مرتجعات

كائن المساعد المطابق للمعرف المحدد.

مثال على مساعد الاسترداد

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

استرداد ملف المساعد

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

استرداد ملف مساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي ينتمي إليه الملف.
file_id سلسلة المطلوب معرف الملف الذي نحصل عليه

المرتجعات

كائن ملف المساعد المطابق للمعرف المحدد

مثال على استرداد ملف المساعد

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

تعديل المساعد

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

تعديل مساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي ينتمي إليه الملف.

نص الطلب

المعلمة نوع مطلوبة ‏‏الوصف
model اختياري اسم نشر النموذج للنموذج المراد استخدامه.
name سلسلة أو قيمة خالية اختياري اسم المساعد. الحد الأقصى للطول هو 256 حرفا.
description سلسلة أو قيمة خالية اختياري وصف المساعد. الحد الأقصى للطول هو 512 حرفا.
instructions سلسلة أو قيمة خالية اختياري إرشادات النظام التي يستخدمها المساعد. الحد الأقصى للطول هو 32768 حرفا.
tools صفيف اختياري الإعدادات الافتراضية إلى []. قائمة بالأدوات الممكنة على المساعد. يمكن أن يكون هناك 128 أداة كحد أقصى لكل مساعد. يمكن أن تكون الأدوات من أنواع code_interpreter أو دالة. function يمكن أن يكون الوصف بحد أقصى 1024 حرفا.
file_ids صفيف اختياري الإعدادات الافتراضية إلى []. قائمة بمعرفات الملفات المرفقة بهذا المساعد. يمكن أن يكون هناك بحد أقصى 20 ملفا مرفقا بالمساعد. يتم ترتيب الملفات حسب تاريخ إنشائها بترتيب تصاعدي. إذا تم إرفاق ملف بالقائمة مسبقا ولكنه لم يظهر في القائمة، حذفه من المساعد.
metadata map اختياري مجموعة من 16 زوجا من قيم المفاتيح التي يمكن إرفاقها بعنصر. يمكن أن يكون هذا مفيدا لتخزين معلومات إضافية حول الكائن بتنسيق منظم. يمكن أن يكون طول المفاتيح 64 حرفا كحد أقصى ويمكن أن تكون القيم بحد أقصى 512 حرفا.

مرتجعات

كائن المساعد المعدل.

مثال على مساعد التعديل

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

حذف مساعد

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

حذف مساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي ينتمي إليه الملف.

مرتجعات

حالة الحذف.

مثال على مساعد الحذف

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

حذف ملف المساعد

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

حذف ملف مساعد.

معلمات المسار

المعلمة نوع مطلوبة ‏‏الوصف
assistant_id سلسلة المطلوب معرف المساعد الذي ينتمي إليه الملف.
file_id سلسلة المطلوب معرف الملف المراد حذفه

مرتجعات

حالة حذف الملف

مثال على حذف ملف المساعد

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

مرجع واجهة برمجة تطبيقات تحميل الملفات

يستخدم المساعدون نفس واجهة برمجة التطبيقات لتحميل الملفات كضبط دقيق. عند تحميل ملف، يجب عليك تحديد قيمة مناسبة لمعلمة الغرض.

كائن مساعد

الحقل نوع الوصف
id سلسلة المعرف، الذي يمكن الرجوع إليه في نقاط نهاية واجهة برمجة التطبيقات.
object سلسلة نوع الكائن، وهو مساعد دائما.
created_at integer الطابع الزمني Unix (بالثوان) لوقت إنشاء المساعد.
name سلسلة أو قيمة خالية اسم المساعد. الحد الأقصى للطول هو 256 حرفا.
description سلسلة أو قيمة خالية وصف المساعد. الحد الأقصى للطول هو 512 حرفا.
model سلسلة اسم نشر النموذج المراد استخدامه.
instructions سلسلة أو قيمة خالية إرشادات النظام التي يستخدمها المساعد. الحد الأقصى للطول هو 32768 حرفا.
tools صفيف قائمة بالأدوات الممكنة على المساعد. يمكن أن يكون هناك 128 أداة كحد أقصى لكل مساعد. يمكن أن تكون الأدوات من أنواع code_interpreter أو دالة. function يمكن أن يكون الوصف بحد أقصى 1024 حرفا.
file_ids صفيف قائمة بمعرفات الملفات المرفقة بهذا المساعد. يمكن أن يكون هناك بحد أقصى 20 ملفا مرفقا بالمساعد. يتم ترتيب الملفات حسب تاريخ إنشائها بترتيب تصاعدي.
metadata map مجموعة من 16 زوجا من قيم المفاتيح التي يمكن إرفاقها بعنصر. يمكن أن يكون هذا مفيدا لتخزين معلومات إضافية حول الكائن بتنسيق منظم. يمكن أن يكون طول المفاتيح 64 حرفا كحد أقصى ويمكن أن تكون القيم بحد أقصى 512 حرفا.

كائن ملف المساعد

الحقل نوع الوصف
id سلسلة المعرف، الذي يمكن الرجوع إليه في نقاط نهاية واجهة برمجة التطبيقات.
object سلسلة نوع الكائن، والذي يكون دائما assistant.file
created_at integer الطابع الزمني Unix (بالثوان) لوقت إنشاء ملف المساعد.
assistant_id سلسلة معرف المساعد الذي يتم إرفاق الملف به.