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

مهم

• يتوفر Foundry Local في المعاينة. توفر إصدارات المعاينة العامة access مبكرة للميزات الموجودة في النشر النشط.
• يمكن أن تتغير الميزات والنهج والعمليات أو لديها قدرات محدودة، قبل التوفر العام (GA).

تنبيه

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

انشر /v1/chat/completeions

تعالج نقطة النهاية هذه طلبات إكمال الدردشة.
إنه متوافق تماما مع واجهة برمجة تطبيقات OpenAI Chat Completions.

نص الطلب:

خصائص ---Standard OpenAI---

• model (سلسلة)
  النموذج المحدد المراد استخدامه للإكمال.
• messages (صفيف)
  محفوظات المحادثات ك قائمة بالرسائل.
  • تتطلب كل رسالة ما يلي:
    • role (سلسلة)
      دور مرسل الرسالة. يجب أن يكون systemأو userأو .assistant
    • content (سلسلة)
      نص الرسالة الفعلي.
• temperature (رقم، اختياري)
  يتحكم في العشوائية، بدءا من 0 إلى 2. تنشئ القيم الأعلى (0.8) مخرجات متنوعة، بينما تنشئ القيم الدنيا (0.2) مخرجات مركزة ومتسقة.
• top_p (رقم، اختياري)
  يتحكم في تنوع اختيار الرمز المميز من 0 إلى 1. تعني القيمة 0.1 أن الرموز المميزة فقط في أعلى 10% احتمال يتم مراعاتها.
• n (عدد صحيح، اختياري)
  عدد الإكمالات البديلة التي يجب إنشاؤها لكل رسالة إدخال.
• stream (منطقي، اختياري)
  عندما يكون صحيحا، يرسل استجابات جزئية للرسائل كأحداث مرسلة من الخادم، تنتهي برسالة data: [DONE] .
• stop (سلسلة أو صفيف، اختياري)
  ما يصل إلى 4 تسلسلات من شأنها أن تتسبب في توقف النموذج عن إنشاء المزيد من الرموز المميزة.
• max_tokens (عدد صحيح، اختياري)
  الحد الأقصى لعدد الرموز المميزة التي يجب إنشاؤها. بالنسبة للنماذج الأحدث، استخدم max_completion_tokens بدلا من ذلك.
• max_completion_tokens (عدد صحيح، اختياري)
  الحد الأقصى لعدد الرموز المميزة التي يمكن للنموذج إنشاؤها، بما في ذلك الإخراج المرئي والرموز المميزة للتفكير.
• presence_penalty (رقم، اختياري)
  القيمة بين -2.0 و2.0. تشجع القيم الإيجابية النموذج على مناقشة مواضيع جديدة من خلال معاقبة الرموز المميزة التي ظهرت بالفعل.
• frequency_penalty (رقم، اختياري)
  القيمة بين -2.0 و2.0. القيم الموجبة تثبط التكرار عن طريق معاقبة الرموز المميزة استنادا إلى تكرارها في النص.
• logit_bias (خريطة، اختيارية)
  ضبط احتمال ظهور رموز مميزة معينة في الاكتمال.
• user (سلسلة، اختيارية)
  معرف فريد للمستخدم النهائي يساعد في المراقبة ومنع إساءة الاستخدام.
• functions (صفيف، اختياري)
  الوظائف المتوفرة التي يمكن للنموذج إنشاء مدخلات JSON لها.
  • يجب أن تتضمن كل دالة ما يلي:
    • name (سلسلة)
      اسم الدالة.
    • description (سلسلة)
      وصف الدالة.
    • parameters (كائن)
      معلمات الدالة الموصوفة ككائن مخطط JSON.
• function_call (سلسلة أو كائن، اختياري)
  يتحكم في كيفية استجابة النموذج لاستدعاءات الوظائف.
  • إذا كان الكائن ، يمكن أن يشمل:
    • name (سلسلة، اختيارية)
      اسم الدالة التي يجب استدعاها.
    • arguments (عنصر، اختياري)
      الوسيطات التي يجب تمريرها إلى الدالة .
• metadata (عنصر، اختياري)
  قاموس أزواج قيمة مفتاح بيانات التعريف.
• top_k (رقم، اختياري)
  عدد أعلى الرموز المميزة للمفردات الاحتمالية التي يجب الاحتفاظ بها لتصفية أعلى k.
• random_seed (عدد صحيح، اختياري)
  بذور لتوليد عدد عشوائي قابل للتكرار.
• ep (سلسلة، اختيارية)
  الكتابة فوق الموفر لنماذج ONNX. يدعم: "dml"، "cuda"، "qnn"، "cpu"، . "webgpu"
• ttl (عدد صحيح، اختياري)
  الوقت للعيش في ثوان للنموذج في الذاكرة.
• tools (عنصر، اختياري)
  الأدوات المحسوبة للطلب.

نص الاستجابة:

• id (سلسلة)
  معرف فريد لإكمال الدردشة.
• object (سلسلة)
  نوع الكائن، دائما "chat.completion".
• created (عدد صحيح)
  الطابع الزمني لإنشاء في ثواني فترة.
• model (سلسلة)
  النموذج المستخدم للإكمال.
• choices (صفيف)
  قائمة بخيارات الإكمال، كل منها يحتوي على:
  • index (عدد صحيح)
    الفهرس من هذا الاختيار.
  • message (كائن)
    الرسالة التي تم إنشاؤها مع:
    • role (سلسلة)
      دائما "assistant" للاستجابات.
    • content (سلسلة)
      النص الفعلي الذي تم إنشاؤه.
  • finish_reason (سلسلة)
    لماذا توقف الجيل (على سبيل المثال، ، "stop"، "length"). "function_call"
• usage (كائن)
  إحصائيات استخدام الرمز المميز:
  • prompt_tokens (عدد صحيح)
    الرموز المميزة في المطالبة.
  • completion_tokens (عدد صحيح)
    الرموز المميزة في الاكتمال.
  • total_tokens (عدد صحيح)
    إجمالي الرموز المميزة المستخدمة.

مثال:

نص الطلب

  {
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "temperature": 0.7,
    "top_p": 1,
    "n": 1,
    "stream": false,
    "stop": null,
    "max_tokens": 100,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": {},
    "user": "user_id_123",
    "functions": [],
    "function_call": null,
    "metadata": {}
  }

هيئة الاستجابة

  {
    "id": "chatcmpl-1234567890",
    "object": "chat.completion",
    "created": 1677851234,
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "I'm doing well, thank you! How can I assist you today?"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 20,
      "total_tokens": 30
    }
  }

POST /v1/audio/transcriptions

تنسخ نقطة النهاية هذه الملفات الصوتية إلى نص. وهو متوافق مع واجهة برمجة تطبيقات OpenAI Audio Transcriptions.

تنسيق الطلب:multipart/form-data

حقول الطلب:

• file (ملف، مطلوب)
  الملف الصوتي المراد نسخه. تتضمن التنسيقات المدعومة MP3 وWAV وFLAC وOGG وWebM.
• model (سلسلة، مطلوب)
  معرف النموذج لاستخدامه في النسخ. استخدم المعرف الذي تم إرجاعه عند تحميل نموذج الهمس (على سبيل المثال، بعد التحميل whisper-tiny).
• language (سلسلة، اختيارية)
  لغة الصوت بتنسيق ISO 639-1 (على سبيل المثال، "en"). توفير هذا يحسن الدقة والسرعة.
• temperature (رقم، اختياري)
  درجة حرارة أخذ العينات بين 0 و1. تنتج القيم الأقل نتائج أكثر حتمية.
• response_format (سلسلة، اختيارية)
  تنسيق الاستجابة. الخيارات: json (افتراضي)، text، . verbose_json

نص الاستجابة:

• text (سلسلة)
  النص المنسوخ.

مثال:

طلب

curl -X POST http://localhost:<PORT>/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -F "model=<MODEL_ID>" \
  -F "language=en"

مهم

استبدل <PORT> بالمنفذ الديناميكي لخدمة Foundry المحلية و <MODEL_ID> بمعرف النموذج الذي تم إرجاعه عند تحميل النموذج. في SDK، استخدم manager.endpoint (JS) أو config.Web.Urls (C#) للحصول على نقطة النهاية - لا تقم أبدا بترميز المنفذ.

هيئة الاستجابة

{
  "text": "This is the transcribed text from the audio file."
}

نصيحة

تتضمن whisper-tinyالأسماء المستعارة المتوفرة لنموذج الهمس و whisper-baseو.whisper-small استخدم هذه الأسماء المستعارة مع SDK لتنزيل النماذج وتحميلها — على سبيل المثال، manager.catalog.getModel("whisper-tiny") في JavaScript.

احصل على /openai/status

احصل على معلومات حالة الخادم.

نص الاستجابة:

• Endpoints (صفيف من السلاسل)
  نقاط نهاية ربط خادم HTTP.
• ModelDirPath (سلسلة)
  الدليل حيث يتم تخزين النماذج المحلية.
• PipeName (سلسلة)
  اسم خادم NamedPipe الحالي.

مثال:

هيئة الاستجابة

  {
    "Endpoints": ["http://localhost:5272"],
    "ModelDirPath": "/path/to/models",
    "PipeName": "inference_agent"
  }

احصل على / مسبك / قائمة

احصل على قائمة بنماذج Foundry Local المتوفرة في الكتالوج.

الاستجابة:

• models (صفيف)
  مصفوفة من كائنات النموذج. يتضمن كل نموذج:
  • name: المعرف الفريد للنموذج.
  • displayName: اسم يمكن للبشر قراءته للنموذج، وغالبا ما يكون نفس الاسم.
  • providerTypeنوع الموفر الذي يستضيف النموذج (على سبيل المثال، AzureFoundry.:
  • uri: عنوان URI للمورد الذي يشير إلى موقع النموذج في السجل.
  • version: رقم إصدار النموذج.
  • modelTypeتنسيق النموذج أو نوعه (على سبيل المثال، ONNX).:
  • promptTemplate:
    • assistant: قالب استجابة المساعد.
    • prompt: قالب تفاعل مساعد المستخدم.
  • publisher: الكيان أو المؤسسة التي نشرت النموذج.
  • taskالمهمة الأساسية التي تم تصميم النموذج لأدائها (على سبيل المثال، إكمال الدردشة.:
  • runtime:
    • deviceTypeنوع الأجهزة التي تم تصميم النموذج للتشغيل عليها (على سبيل المثال، وحدة المعالجة المركزية).:
    • executionProvider: موفر التنفيذ المستخدم لتشغيل النموذج.
  • fileSizeMb: حجم ملف النموذج بالميغابايت.
  • modelSettings:
    • parameters: قائمة بالمعلمات القابلة للتكوين للنموذج.
  • alias: اسم بديل أو اختصار للنموذج
  • supportsToolCalling: يشير إلى ما إذا كان النموذج يدعم وظيفة استدعاء الأدوات.
  • license: نوع الترخيص الذي يتم توزيع النموذج بموجبه.
  • licenseDescription: وصف مفصل أو ارتباط لشروط الترخيص.
  • parentModelUri: عنوان URI للنموذج الأصل الذي يتم اشتقاق هذا النموذج منه.

احصل على / openai / نماذج

احصل على قائمة بالنماذج المخزنة مؤقتا، بما في ذلك النماذج الخارجية المحلية والمسجلة.

الاستجابة:

• 200 جيد
  صفيف من أسماء النماذج كسلاسل.

مثال:

هيئة الاستجابة

  ["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

POST / openai / تنزيل

قم بتنزيل نموذج من الكتالوج إلى storage المحلية.

‏‫ملاحظة‬

يمكن أن تستغرق تنزيلات النموذج الكبيرة وقتا طويلا. تعيين مهلة عالية لهذا الطلب لتجنب الإنهاء المبكر.

نص الطلب:

• model (WorkspaceInferenceModel كائن)
  • Uri (سلسلة)
    نموذج URI لتنزيله.
  • Name (سلسلة) اسم النموذج.
  • ProviderType (سلسلة، اختيارية)
    نوع الموفر (على سبيل المثال، "AzureFoundryLocal"، ). "HuggingFace"
  • Path (سلسلة، اختيارية)
    المسار البعيد إلى ملفات النموذج. على سبيل المثال، في مستودع Hugging Face، هذا هو المسار إلى ملفات النموذج.
  • PromptTemplate (Dictionary<string, string>اختياري)
    يشمل:
    • system (سلسلة، اختيارية)
      قالب رسالة النظام.
    • user (سلسلة، اختيارية) قالب رسالة المستخدم.
    • assistant (سلسلة، اختيارية)
      قالب استجابة المساعد.
    • prompt (سلسلة، اختيارية)
      قالب تفاعل مساعد المستخدم.
  • Publisher (سلسلة، اختيارية)
    publisher النموذج.
• token (سلسلة، اختيارية)
  رمز المصادقة المميز للنماذج المحمية (GitHub أو عناق الوجه).
• progressToken (عنصر، اختياري)
  ل AITK فقط. رمز مميز لتتبع تقدم التنزيل.
• customDirPath (سلسلة، اختيارية)
  دليل التنزيل المخصص (يستخدم ل CLI، غير مطلوب ل AITK).
• bufferSize (عدد صحيح، اختياري)
  حجم المخزن المؤقت لتنزيل HTTP في KB. لا يوجد أي تأثير على NIM أو Azure نماذج Foundry.
• ignorePipeReport (منطقي، اختياري)
  إذا true، يفرض إعداد تقارير التقدم عبر دفق HTTP بدلا من الأنابيب. الإعدادات الافتراضية ل false AITK وS true foundry Local.

استجابة الدفق:

أثناء التنزيل، يقوم الخادم ببث تحديثات التقدم بالتنسيق:

("file name", percentage_complete)

نص الاستجابة النهائي:

• Success (منطقي)
  ما إذا كان التنزيل قد اكتمل بنجاح.
• ErrorMessage (سلسلة، اختيارية)
  تفاصيل الخطأ إذا فشل التنزيل.

مثال:

طلب URI

POST /openai/download

نص الطلب

لاحظ أنه يجب توفير لاحقة الإصدار في اسم النموذج.

{
  "model": {
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu:4",
    "Publisher": "",
    "PromptTemplate": {
      "system": "<|system|>{Content}<|end|>",
      "user": "<|user|>{Content}<|end|>",
      "assistant": "<|assistant|>{Content}<|end|>",
      "prompt": "<|user|>{Content}<|end|><|assistant|>"
    }
  }
}

تدفق الاستجابة

  ("genai_config.json", 0.01)
  ("genai_config.json", 0.2)
  ("model.onnx.data", 0.5)
  ("model.onnx.data", 0.78)
  ...
  ("", 1)

الاستجابة النهائية

  {
    "Success": true,
    "ErrorMessage": null
  }

احصل على /openai/load/{name}

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

معلمات URI:

• name (سلسلة)
  اسم النموذج المراد تحميله.

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

• unload (منطقي، اختياري)
  ما إذا كنت تريد إلغاء تحميل النموذج تلقائيا بعد وقت الخمول. الإعدادات الافتراضية لـ true.
• ttl (عدد صحيح، اختياري)
  وقت العيش بالثوان. إذا كانت أكبر من 0، فإن هذه القيمة تتجاوز المعلمة unload .
• ep (سلسلة، اختيارية)
  موفر التنفيذ لتشغيل هذا النموذج. يدعم: "dml"، "cuda"، "qnn"، "cpu"، . "webgpu"
  إذا لم يتم تحديده، يستخدم الإعدادات من genai_config.json.

الاستجابة:

• 200 جيد
  نص استجابة فارغ

مثال:

طلب URI

  GET /openai/load/Phi-4-mini-instruct-generic-cpu?ttl=3600&ep=dml

احصل على /openai/unload/{name}

إلغاء تحميل نموذج من الذاكرة.

معلمات URI:

• name (سلسلة) اسم النموذج المراد إلغاء تحميله.

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

• force (منطقي، اختياري) إذا true، يتجاهل إعدادات TTL وتفريغها على الفور.

الاستجابة:

• نص استجابة فارغ 200 OK

مثال:

طلب URI

GET /openai/unload/Phi-4-mini-instruct-generic-cpu?force=true

احصل على / openai / unloadall

إلغاء تحميل جميع النماذج من الذاكرة.

الاستجابة:

• 200 جيد
  نص استجابة فارغ

GET / openai / loadedmodels

احصل على قائمة الطرز التي تم تحميلها حاليا.

الاستجابة:

• 200 جيد
  صفيف من أسماء النماذج كسلاسل.

مثال:

هيئة الاستجابة

["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

احصل على / openai / getgpudevice

احصل على معرف جهاز GPU الحالي.

الاستجابة:

• 200 جيد
  عدد صحيح يمثل معرف جهاز GPU الحالي.

احصل على /openai/setgpudevice/{deviceId}

قم بتعيين جهاز GPU النشط.

معلمات URI:

• deviceId (عدد صحيح)
  معرف جهاز GPU المراد استخدامه.

الاستجابة:

• 200 جيد
  نص استجابة فارغ

مثال:

• طلب URI

  GET /openai/setgpudevice/1
  

POST /v1/chat/completeions/tokenizer/encode/count

حساب الرموز المميزة لطلب إكمال دردشة معين دون إجراء استدلال.

نص الطلب:

• نوع المحتوى: application/json
• كائن JSON بالتنسيق ChatCompletionCreateRequest مع:
  • model (سلسلة)
    نموذج لاستخدامه للرمز المميز.
  • messages (صفيف)
    صفيف من كائنات الرسائل مع role و content.

نص الاستجابة:

• نوع المحتوى: application/json
• كائن JSON مع عدد الرموز المميزة:
  • tokenCount (عدد صحيح)
    عدد الرموز المميزة في الطلب.

مثال:

نص الطلب

  {
    "messages": [
      {
        "role": "system",
        "content": "This is a system message"
      },
      {
        "role": "user",
        "content": "Hello, what is Microsoft?"
      }
    ],
    "model": "Phi-4-mini-instruct-cuda-gpu"
  }

هيئة الاستجابة

  {
    "tokenCount": 23
  }