AIProxyServer - Opas

Näin pääset alkuun

1. Käynnistä sovellus

Avaa AIProxyServer. Ensimmäisellä käynnistyskerralla välityspalvelin käynnistyy automaattisesti ja kuuntelee portissa 8421 paikallisella tietokoneellasi. Pääikkunassa on kolme osiota:

• Välityspalvelin — nykyinen tila, perus-URL ja painike kuuntelijan käynnistämiseen tai pysäyttämiseen
• Bearer-tunnus — valinnainen todennuksen kytkin ja tunnuksen näyttö
• Palveluntarjoajat — jokainen tuettu pilvi-AI-palveluntarjoaja sekä Aseta API-avain -painike kullakin rivillä

2. Lisää ensimmäinen API-avaimesi

1. Valitse mikä tahansa palveluntarjoaja Palveluntarjoajat-luettelosta (esimerkiksi OpenAI (ChatGPT))
2. Napsauta Hae API-avain avataksesi palveluntarjoajan hallintakonsolin selaimessa. Luo tai kopioi avain
3. Napsauta Aseta API-avain samalta riviltä ja liitä arvo valintaikkunaan
4. Napsauta Tallenna. Tilatunnus vaihtuu muotoon Määritetty vihreänä

3. Yhdistä asiakassovellus

Ohjaa mikä tahansa OpenAI-yhteensopiva asiakas välityspalvelimeen. Perus-URL on http://localhost:8421/<provider>/v1. Palveluntarjoajaosio valitsee, mikä pilvipalvelu vastaanottaa pyynnön.

# 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)

Asiakas ei koskaan näe todellista avainta. AIProxyServer liittää ylävirran tunnistetiedot välittäessään pyynnön.

Käyttöliittymän yleiskatsaus

Välityspalvelin-paneeli

Bearer-tunnus-paneeli

• Vaadi Bearer-tunnuksen todennus — valintaruutu, joka ottaa todennuksen käyttöön tai poistaa sen käytöstä. Oletuksena pois päältä vaivatonta paikallista käyttöä varten.
• Tunnuskenttä — nykyisen tunnuksen vain luku -näyttö. Näytetään pisteinä; käytä Kopioi napataksesi sen.
• Luo uudelleen — luo uuden satunnaisen tunnuksen. Nykyiset asiakkaat on päivitettävä uudella arvolla.

Palveluntarjoajat-paneeli

Yksi rivi kutakin tuettua pilvipalveluntarjoajaa kohden. Jokaisella rivillä näkyy:

• Näyttönimi (esimerkiksi Claude (Anthropic))
• Määritystila — vihreä Määritetty kun API-avain on tallennettu, harmaa Ei määritetty muulloin
• URL-polku, jota asiakkaasi käyttävät, esim. /anthropic/v1/chat/completions
• Aseta API-avain — avaa valintaikkunan tunnistetietojen syöttämistä varten
• Hae API-avain — avaa palveluntarjoajan hallintakonsolin selaimessa

Tuetut palveluntarjoajat

Yksitoista pilvipohjaista AI-palvelua sisältyy pakettiin. Useimmat käyttävät OpenAI Chat Completions -muotoa natiivisti ja välitetään sellaisenaan. Kolme (Anthropic, Gemini, ERNIE) käyttävät omia protokolliaan; AIProxyServer kääntää pyynnöt ja vastaukset lennossa, joten asiakkaasi näkee vain OpenAI-muodon.

Palveluntarjoajakohtaiset huomautukset

• Azure OpenAI — liitä koko käyttöönoton päätepiste kenttään Endpoint Base URL esimerkiksi https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Välityspalvelin lisää /chat/completions?api-version=2024-02-01 automaattisesti.
• ERNIE — Baidu Qianfan käyttää OAuthia, joten sekä API Key että Secret Key vaaditaan. AIProxyServer pyytää ja tallentaa käyttöoikeustunnukset välimuistiin taustalla.
• Gemini — todennus tehdään URL-kyselyparametrilla; välityspalvelin lisää sen puolestasi. Maksuttoman tason minuuttikohtaiset kiintiöt ovat silti voimassa.

API-viite

Päätepisteet

Suoratoisto

Kun asiakas lähettää "stream": true, välityspalvelin vastaa Server-Sent Events -tapahtumilla OpenAI-muodossa:

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

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

data: [DONE]

Anthropicin ja Geminin natiivit virrat käännetään tähän muotoon, jotta kaikki asiakkaat voivat käyttää yhtä jäsennintä.

Todennusotsake

Kun Vaadi Bearer-tunnuksen todennus on käytössä, lähetä pääikkunassa näkyvä tunnus jokaisen pyynnön mukana:

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

Asetukset

Avaa Asetukset-ikkuna alatyökalurivin rataskuvakkeesta.

Asiakasesimerkit

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

Vinkit

• Pidä Bearer-tunnus pois käytöstä kehittäessäsi paikallisesti; ota se käyttöön heti, kun otat LAN-yhteyden käyttöön.
• Käytä asiakaskoodissasi eri Perus-URL-osoitetta kullekin palveluntarjoajalle, jotta voit vaihtaa palveluntarjoajaa muuttamalla yhtä vakiota.
• Välityspalvelin käynnistyy automaattisesti, mutta voit pysäyttää sen tilapäisesti pääikkunasta, jos porttiristiriita ilmenee.
• Jos palveluntarjoajan maksuton taso rajoittaa pyyntöjäsi, ylävirran virheilmoitus välitetään sellaisenaan. Asiakkaalta ei piiloteta uudelleenyrityslogiikkaa.
• Päätepiste /v1/providers -päätepiste on hyödyllinen, kun haluat selvittää, mitkä palveluntarjoajat on määritetty ajonaikana.

Vianmääritys

Välityspalvelin ei käynnisty

• Toinen prosessi saattaa jo käyttää porttia 8421. Vaihda portti asetuksista ja käynnistä välityspalvelin uudelleen.
• Tarkista järjestelmälokista käynnistyshetkellä näytetty virheilmoitus.

Pyyntö palauttaa virheen 401 Unauthorized

• Bearer-tunnusvaatimus on käytössä, mutta asiakas ei lähettänyt vastaavaa Authorization: Bearer ... -otsaketta.
• Palveluntarjoajan oma API-avain voi olla virheellinen — ylävirran virhe välitetään, joten tarkista viestin runko.

Pyyntö palauttaa virheen "API key is not configured"

• Avaa Palveluntarjoajat-luettelo ja napsauta Aseta API-avain kyseisen palveluntarjoajan kohdalla.
• ERNIEä varten sekä API Key että Secret Key on täytettävä. Azure OpenAIta varten vaaditaan myös Endpoint Base URL.

Mobiililaite ei tavoita välityspalvelinta

• Ota käyttöön Salli LAN-yhteys asetuksissa.
• Käytä Perus-URL-kentässä näkyvää LAN-IP-osoitetta, älä localhost.
• Varmista, että molemmat laitteet ovat samassa Wi-Fi-verkossa ja että palomuurisi sallii saapuvat yhteydet välityspalvelimen porttiin.

Suoratoistovastaukset saapuvat kerralla

• Varmista, että asiakkaasi lähettää "stream": true JSON-rungossa.
• Jotkin HTTP-kirjastot puskuroivat SSE:n oletuksena — poista vastauspuskurointi käytöstä asiakaspuolella.

Tietosuoja

• API-avaimet tallennetaan salattuina Fernetillä sijaintiin ~/Library/Application Support/AIProxyServer/credentials.enc. Salausavain sijainnissa master.key on käyttöoikeuksilla 0600.
• Bearer-tunnus tallennetaan käyttöön otettuna myös vain salattuun holviin eikä sitä koskaan kirjoiteta tavalliseen asetustiedostoon.
• Välityspalvelin välittää pyynnöt vain palveluntarjoajille, jotka olet itse määrittänyt. Se ei tee muita lähteviä kutsuja.
• Ei telemetriaa, analytiikkaa eikä kaatumisraportointia.
• Verkon oletussidonta on 127.0.0.1 vain. LAN-altistus on valinnainen.
• Keskustelujen sisältöä ei tallenneta. AIProxyServer välittää tavut ja unohtaa ne heti.