Łączenie aplikacji

Punkt końcowy Model Router jest zgodny z OpenAI — skieruj dowolny SDK OpenAI, framework lub narzędzie obsługujące BYOK na bazowy adres URL Performance Hub, uwierzytelnij się jednym ze swoich kluczy API i wszystko po prostu działa. Ta strona to szybki start integracji.

Czego potrzebujesz

1. Klucza API. Aby go utworzyć, musisz mieć rolę Organisation Administrator. Utwórz go w Settings (koło zębate) → Service Access & API Keys → Create key. Klucze zaczynają się od phk_, a sekret jest wyświetlany tylko raz. Zobacz Klucze API.
2. Bazowego adresu URL. Jest wyświetlany na karcie Connecting to the API na tej samej stronie ustawień:

Rysunek 1: Connecting to the API: bazowy adres URL i przykładowe żądanie do skopiowania

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

Dokładny bazowy adres URL dla Twojego środowiska jest zawsze wyświetlany w module — kopiuj go stamtąd, a nie z tej strony.

Uwierzytelnianie

Wysyłaj klucz jako token typu bearer w każdym żądaniu:

Authorization: Bearer phk_your_key_here

Traktuj klucz jak hasło. Jeśli wycieknie, zrotuj go akcją Rotate (zostanie wystawiony nowy sekret, a stary natychmiast przestanie działać) lub unieważnij akcją Revoke na liście kluczy API.

Pierwsze żądanie

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"}]}'

"Użyj modelu 'auto', aby router wybrał najlepszy model dla każdego żądania, lub dowolnego ID modelu włączonego dla Twojego obiektu."

Python (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);

Pobieranie listy modeli

GET /v1/models zwraca wszystkie modele włączone dla Twojego obiektu (z uwzględnieniem ograniczeń modeli ustawionych dla klucza). Pobieranie listy modeli działa nawet przy zerowym saldzie, dzięki czemu integracje mogą poznać katalog, zanim konto zostanie zasilone.

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

Użyj dowolnego zwróconego identyfikatora modelu w polu model lub użyj auto, aby Auto Router wybierał najlepszy model dla każdego żądania.

Przesyłanie strumieniowe

Przesyłanie strumieniowe działa w standardowy sposób OpenAI — ustaw "stream": true i odbieraj fragmenty zdarzeń wysyłanych przez serwer (server-sent events). Powyższe przykłady SDK obsługują je za pomocą zwykłych interfejsów API do przesyłania strumieniowego.

Modele zapasowe

Możesz podać uporządkowany łańcuch modeli zapasowych, aby w razie niepowodzenia modelu podstawowego żądanie zostało ponowione na następnym:

• models: ["model-a", "model-b", "model-c"] — pełna uporządkowana lista; pierwsza pozycja jest modelem podstawowym.
• lub model: "model-a" wraz z fallbacks: ["model-b", "model-c"] — modele zapasowe próbowane po modelu podstawowym.

Kandydaci zapasowi są filtrowani do modeli, z których Twój klucz może korzystać.

Odpowiedzi błędów

Błędy mają standardową strukturę błędu OpenAI: { "error": { "message", "type", "code" } }.

Oba błędy 402 zawierają pole docsUrl, a ich komunikat kończy się łączem do dokumentacji Performance Hub.

Obsługuj błąd 402 w integracji w kontrolowany sposób — to oczekiwany sygnał, że na koncie skończyły się środki lub osiągnięto budżet, a nie usterka.

Dobre praktyki

• Jeden klucz na system. Przydziel każdej integracji własny, opisany etykietą klucz, aby wykorzystanie można było przypisać na kartach Activity i Logs, a wyciek wymagał zrotowania tylko jednego klucza.
• Ogranicz każdy klucz. Ustaw limity wydatków i limity liczby żądań odpowiednie dla danego systemu; zobacz Klucze API.
• Preferuj auto, chyba że potrzebujesz konkretnego modelu — proste zadania obsługują szybkie, tanie modele, a najmocniejsze modele są używane tylko wtedy, gdy zadanie tego wymaga.
• Obserwuj kartę Logs podczas integracji — każde żądanie pojawia się ze stanem, liczbą tokenów i kosztem, co przyspiesza diagnozowanie problemów z integracją. Zobacz Aktywność i dzienniki.