ربط تطبيقك

نقطة نهاية Model Router متوافقة مع OpenAI: وجّه أي OpenAI SDK أو إطار عمل أو أداة تدعم BYOK إلى عنوان URL الأساسي لـ Performance Hub، وصادق باستخدام أحد مفاتيح API الخاصة بك، وسيعمل كل شيء مباشرة. هذه الصفحة هي دليل البدء السريع للتكامل.

ما تحتاج إليه

1. مفتاح API. يجب أن تكون Organisation Administrator لإنشاء مفتاح. أنشئه ضمن الإعدادات (رمز الترس) ← Service Access & API Keys ← Create key. تبدأ المفاتيح بـ phk_ ولا يُعرض السر إلا مرة واحدة. راجع مفاتيح API.
2. عنوان URL الأساسي. يُعرض في بطاقة Connecting to the API في صفحة الإعدادات نفسها:

الشكل 1: Connecting to the API: عنوان URL الأساسي ومثال على طلب جاهز للنسخ واللصق

https://app.performancehub.co/ai/v1

يُعرض عنوان URL الأساسي الدقيق لبيئتك دائمًا في الوحدة، لذا انسخه من هناك بدلًا من هذه الصفحة.

المصادقة

أرسل مفتاحك كرمز حامل (bearer token) مع كل طلب:

Authorization: Bearer phk_your_key_here

تعامل مع المفتاح كما تتعامل مع كلمة المرور. إذا تسرّب، فاستخدم Rotate (يُصدر سر جديد ويتوقف السر القديم عن العمل فورًا) أو Revoke من قائمة مفاتيح API.

طلبك الأول

curl

curl https://app.performancehub.co/ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

"استخدم النموذج 'auto' لتمكين الموجه من اختيار أفضل نموذج لكل طلب، أو أي معرف نموذج مفعل لمنشأتك."

بايثون (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://app.performancehub.co/ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

TypeScript / Node (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://app.performancehub.co/ai/v1',
  apiKey: process.env.PH_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'auto',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(response.choices[0].message.content);

عرض قائمة النماذج

يعيد GET /v1/models كل نموذج مفعّل لمنشأتك (مع مراعاة أي تقييد للنماذج على مستوى المفتاح). يعمل عرض قائمة النماذج حتى عندما يكون رصيدك صفرًا، لذا يمكن للتكاملات اكتشاف الكتالوج قبل تمويل الحساب.

curl https://app.performancehub.co/ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

استخدم أي معرّف نموذج مُعاد في الحقل model، أو استخدم auto ليختار Auto Router أفضل نموذج لكل طلب.

البث

يعمل البث بطريقة OpenAI القياسية: عيّن "stream": true واستهلك أجزاء الأحداث المرسلة من الخادم. تدعم أمثلة SDK أعلاه ذلك عبر واجهات البث المعتادة الخاصة بها.

النماذج الاحتياطية

يمكنك تقديم سلسلة احتياطية مرتّبة بحيث إذا فشل النموذج الأساسي، يُعاد محاولة الطلب على النموذج التالي:

• models: ["model-a", "model-b", "model-c"]: قائمة مرتّبة كاملة؛ والعنصر الأول هو النموذج الأساسي.
• أو model: "model-a" إضافة إلى fallbacks: ["model-b", "model-c"]: نماذج احتياطية تُجرَّب بعد النموذج الأساسي.

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

استجابات الأخطاء

تستخدم الأخطاء بنية أخطاء OpenAI القياسية: { "error": { "message", "type", "code" } }.

يتضمن كلا الخطأين 402 الحقل docsUrl، وتنتهي رسالتهما برابط إلى وثائق Performance Hub.

تعامل مع الخطأ 402 بسلاسة في التكامل لديك، فهو الإشارة المتوقعة عندما ينفد رصيد الحساب أو يبلغ ميزانية، وليس عطلًا.

ممارسات جيدة

• مفتاح واحد لكل نظام. امنح كل تكامل مفتاحه الخاص بتسمية مميزة حتى يمكن نسب الاستخدام في Activity وLogs، ولا يتطلب التسريب سوى تدوير مفتاح واحد.
• قيّد كل مفتاح. اضبط سقوف إنفاق وحدود معدل لكل مفتاح تناسب النظام؛ راجع مفاتيح API.
• فضّل auto ما لم تكن بحاجة إلى نموذج محدد، فتحصل على نماذج سريعة ومنخفضة التكلفة للعمل البسيط، ولا تُستخدم أقوى النماذج إلا عندما تحتاج إليها المهمة.
• راقب علامة التبويب Logs أثناء التكامل، إذ يظهر كل طلب بحالته ورموزه المميزة وتكلفته، مما يسرّع تصحيح مشكلات التكامل. راجع النشاط والسجلات.