AIProxyServer - מדריך

תחילת העבודה

1. הפעלת האפליקציה

פתחו את AIProxyServer. בהפעלה הראשונה ה‑proxy מתחיל אוטומטית ומאזין על פורט 8421 במחשב המקומי שלכם. החלון הראשי מציג שלושה אזורים:

• Proxy Server — הסטטוס הנוכחי, base URL, וכפתור להפעלה או עצירה של המאזין
• Bearer Token — מתג אימות אופציונלי ותצוגת אסימון
• Providers — כל ספקי ה‑AI הענן הנתמכים, עם כפתור Set API Key בכל שורה

2. הוספת מפתח ה‑API הראשון שלכם

1. בחרו ספק כלשהו מרשימת Providers (למשל OpenAI (ChatGPT))
2. לחצו על Get API key כדי לפתוח את הקונסול של הספק בדפדפן, ואז צרו או העתיקו מפתח
3. לחצו על Set API Key באותה שורה והדביקו את הערך לדיאלוג
4. לחצו על Save. תווית הסטטוס תשתנה ל‑Configured בירוק

3. חיבור אפליקציית לקוח

הפנו כל לקוח תואם OpenAI אל ה‑proxy. ה‑Base URL הוא http://localhost:8421/<provider>/v1. החלק provider קובע לאיזה ענן יישלח הבקשה.

# Example: OpenAI Python SDK pointed at the proxy
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

הלקוח לעולם לא רואה את המפתח האמיתי. AIProxyServer מצרף את הזהויות במעלה הזרם כאשר הוא מעביר את הבקשה.

סקירת ממשק

פאנל Proxy Server

פאנל Bearer Token

• Require Bearer Token authentication — תיבת סימון המפעילה או מכבה את האימות. כבויה כברירת מחדל לשימוש מקומי קל.
• Token field — תצוגה לקריאה בלבד של האסימון הנוכחי. מוצג כנקודות; השתמשו ב‑Copy כדי לקבל אותו.
• Regenerate — הפיקו אסימון אקראי חדש. לקוחות קיימים חייבים להתעדכן עם הערך החדש.

פאנל Providers

שורה אחת לכל ספק ענן נתמך. כל שורה מציגה:

• שם התצוגה (למשל Claude (Anthropic))
• סטטוס הגדרה — Configured ירוק כאשר מפתח API נשמר, Not configured אפור אחרת
• נתיב ה‑URL שבו הלקוחות שלכם משתמשים, למשל /anthropic/v1/chat/completions
• Set API Key — פותח דיאלוג להזנת אישורי גישה
• Get API key — פותח את הקונסול של הספק בדפדפן

ספקים נתמכים

אחד‑עשר שירותי AI ענן מצורפים. רובם משתמשים בפורמט OpenAI Chat Completions בצורה מקורית ומועברים כפי שהם. שלושה (Anthropic, Gemini, ERNIE) משתמשים בפרוטוקולים משלהם; AIProxyServer מתרגם בקשות ותגובות בזמן אמת כך שהלקוח שלכם רואה תמיד רק את צורות OpenAI.

הערות ייחודיות לכל ספק

• Azure OpenAI — הדביקו את כתובת נקודת הקצה לפריסה המלאה לתוך השדה Endpoint Base URL, למשל https://my-resource.openai.azure.com/openai/deployments/gpt-4o. ה‑proxy מוסיף אוטומטית /chat/completions?api-version=2024-02-01.
• ERNIE — Baidu Qianfan משתמש ב‑OAuth, אז גם API Key וגם Secret Key נדרשים. AIProxyServer מבקש אסימוני גישה ושומר אותם במטמון מאחורי הקלעים.
• Gemini — האימות הוא לפי פרמטר שאילתת URL; ה‑proxy מוסיף אותו עבורכם. מכסות לדקה של השכבה החינמית עדיין חלות.

מקור API

נקודות קצה

הזרמה

כאשר הלקוח שולח "stream": true, ה‑proxy מגיב ב‑Server-Sent Events בפורמט של OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

ההזרמות המקוריות של Anthropic ו‑Gemini מתורגמות לצורה זו כך שכל הלקוחות יכולים להשתמש במנתח אחד.

כותרת אימות

כאשר Require Bearer Token authentication מופעל, שלחו את האסימון מהחלון הראשי עם כל בקשה:

Authorization: Bearer <token-shown-in-app>

הגדרות

פתחו את חלון Settings מסמל גלגל השיניים בסרגל הכלים התחתון.

דוגמאות לקוח

cURL

# OpenAI (passthrough)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude via the same OpenAI shape
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # ignored when Bearer Token is off
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Using any OpenAI-compatible Dart client
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // unused when Bearer Token is off
);

טיפים

• השאירו את Bearer Token כבוי בזמן שאתם מפתחים מקומית; הפעילו אותו ברגע שאתם מפעילים גישת LAN.
• השתמשו ב‑Base URL נפרד לכל ספק בקוד הלקוח שלכם כדי שתוכלו להחליף ספקים על ידי שינוי קבוע אחד.
• ה‑proxy מופעל אוטומטית, אך תוכלו לעצור אותו זמנית מהחלון הראשי אם מתרחש קונפליקט פורטים.
• אם השכבה החינמית של ספק מגבילה את קצב הבקשות שלכם, הודעת השגיאה במעלה הזרם מועברת מילולית. אין לוגיקת ניסיון חוזר מוסתרת מהלקוח.
• נקודת הקצה /v1/providers שימושית לגילוי אילו ספקים מוגדרים בזמן ריצה.

פתרון בעיות

ה‑proxy לא יעלה

• תהליך אחר עשוי כבר להשתמש בפורט 8421. שנו את הפורט ב‑Settings והפעילו מחדש את ה‑proxy.
• בדקו את יומן המערכת לאיתור הודעת השגיאה שמוצגת בזמן הפעלה.

בקשה מחזירה 401 Unauthorized

• דרישת Bearer Token מופעלת אך הלקוח לא שלח כותרת Authorization: Bearer ... תואמת.
• מפתח ה‑API של הספק עצמו עשוי להיות לא תקף — השגיאה במעלה הזרם מועברת, אז בדקו את גוף ההודעה.

בקשה מחזירה "API key is not configured"

• פתחו את רשימת Providers ולחצו על Set API Key עבור הספק המדובר.
• עבור ERNIE, יש למלא גם את API Key וגם את Secret Key. עבור Azure OpenAI, נדרש גם Endpoint Base URL.

מכשיר נייד לא מצליח להגיע ל‑proxy

• הפעילו את Allow LAN Access ב‑Settings.
• השתמשו בכתובת ה‑IP של רשת ה‑LAN המוצגת בשדה Base URL, ולא ב‑localhost.
• ודאו ששני המכשירים נמצאים באותה רשת Wi-Fi ושחומת האש שלכם מאפשרת חיבורים נכנסים על פורט ה‑proxy.

תגובות הזרמה מגיעות בבת אחת

• ודאו שהלקוח שלכם שולח "stream": true בגוף ה‑JSON.
• חלק מספריות ה‑HTTP מאחסנות SSE כברירת מחדל — השביתו את אחסון התגובה בצד הלקוח.

פרטיות

• מפתחות API נשמרים מוצפנים עם Fernet ב‑~/Library/Application Support/AIProxyServer/credentials.enc. למפתח ההצפנה ב‑master.key יש הרשאות 0600.
• ה‑Bearer Token, כאשר מופעל, נשמר גם הוא רק בכספת המוצפנת ולעולם לא נכתב לקובץ ההגדרות הרגיל.
• ה‑proxy מעביר בקשות רק לספקים שהגדרתם במפורש. הוא לא מבצע שיחות יוצאות אחרות.
• ללא טלמטריה, ללא ניתוחים, ללא דיווח קריסות.
• קישור הרשת המוגדר כברירת מחדל הוא 127.0.0.1 בלבד. חשיפה ל‑LAN דורשת הסכמה מפורשת.
• תוכן השיחות לא נשמר. AIProxyServer מעביר בתים ושוכח אותם מיד.