אימות באמצעות מפתח API

שער CLEVI מאמת את הנתיבים התואמים ל-OpenAI ואת הנתיבים התואמים ל-Anthropic באמצעות מפתח API אחד.
הערכים שיש להגדיר בלקוח הם כותרת האימות המכילה את המפתח וה-base URL של ה-SDK, וישנם הבדלים בפורמטים המותרים של הכותרת וב-base URL בהתאם למפרט.
לאחר השלמת ההגדרה, ניתן לאמת מיד אם האימות הצליח על ידי שליפת רשימת המודלים.
אם האימות נכשל, מוחזר 401; אם האימות עבר אך לא מתקיימים תנאי ההרשאה או המכסה, מוחזר 403.

הנפיקו את מפתח ה-API במסך מפתחות ה-API שבקונסולה. באותו מסך ניתן לנהל את ביטול המפתח ואת טווח השימוש בו.

כותרת אימות

בשני המפרטים, מפתח ה-API נכלל בכותרת בקשה אחת. משתמשים באחת מהכותרות X-API-Key או Authorization, והפורמט המותר משתנה בהתאם למפרט.

בעת שימוש בכותרת Authorization בנתיב התואם ל-OpenAI, נדרשת קידומת Bearer. אם שולחים רק את המפתח ללא הקידומת, השער דוחה את הבקשה.

שמות הכותרות אינם תלויי-רישיות, ולכן גם כותרת x-api-key שנשלחת על ידי Anthropic SDK פועלת כמות שהיא. אם מציינים את שתי הכותרות, הערך של X-API-Key מקבל עדיפות.

base URL

ניתן להמשיך להשתמש ב-SDK הקיים על ידי שינוי ה-base URL בלבד לכתובות שלהלן. שני הכתובות נבדלות בשאלה אם הן כוללות את /v1, לכן יש לציין את הכתובת המתאימה למפרט כמות שהיא.

בדיקת האימות

לאחר הגדרת המפתח וכתובת ה-base URL, ניתן לאחזר את רשימת המודלים כדי לוודא אם האימות הצליח. הדוגמאות שלהלן מריצות את אותה שאילתה באמצעות curl, OpenAI SDK ו-Anthropic SDK. במקום sk-... יש להזין את המפתח שהונפק במסך מפתחות ה-API.

בעת אחזור באמצעות curl, יש לציין את הנתיב המלא עד /v1/models בשני המפרטים. הפקודה הראשונה משתמשת בכותרת X-API-Key בנתיב התואם ל-OpenAI, והפקודה השנייה משתמשת בכותרת Authorization בנתיב התואם ל-Anthropic.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

ב-OpenAI SDK, יש לציין ב-base_url כתובת הכוללת את /v1.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

ב-Anthropic SDK, יש לציין ב-base_url כתובת המסתיימת לפני /v1.
לצורך האימות, יש להשתמש כפי שהוא בכותרת x-api-key שה-SDK שולח.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

בכל אחת מהדוגמאות, תגובה 200 מעידה שהאימות הצליח, ובשדה data של התגובה נמצאת רשימת המודלים שניתן לקרוא להם באמצעות מפתח זה. אם מתקבלת תגובה 401, בדקו את הסיבה לפי הסדר שבסעיף הבא.

אימות נכשל

אם נשלח מפתח חסר, שפג תוקפו או שבוטל, תוחזר תגובה 401. בעת קריאה ללא מפתח בנתיב התואם ל-OpenAI, יוחזר גוף התגובה שלהלן, ובנתיב התואם ל-Anthropic הערך של error.type יהיה authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

אם התקבלה תגובה 401, בדקו לפי הסדר הבא.

1. בדקו את מצב המפתח במסך מפתחות ה-API. אם המפתח פג תוקף או בוטל, הנפיקו מפתח חדש.
2. בדקו ששם הכותרת הוא X-API-Key או Authorization.
3. אם אתם משתמשים בכותרת Authorization בנתיב התואם ל-OpenAI, בדקו אם קידומת Bearer קיימת.

לאחר התיקון, הריצו שוב את אחזור רשימת המודלים שבסעיף אימות ובדקו אם מתקבלת תגובה 200.

כותרות לשימוש משותף

כל הכותרות הבאות הן אופציונליות. כדי לאפשר מעקב אחר בעיות, מומלץ להגדיר את X-Request-Id.

אם שגיאות 5xx חוזרות על עצמן, יש לדווח עליהן דרך העזרה והפנייה, בצירוף X-Request-Id. אם זהו ערך שצוין ישירות, ניתן להשוות אותו מיד לרישומי הלקוח.