AIProxyServer - Opas

Aloittaminen

1. Käynnistä sovellus

Avaa AIProxyServer. Ensimmäisellä käynnistyksellä proxy käynnistyy automaattisesti ja kuuntelee paikallisen koneesi porttia 8421. Pääikkunassa näkyy kolme osiota:

• Proxy Server — nykyinen tila, perus-URL ja painike kuuntelijan käynnistämistä tai pysäyttämistä varten
• Bearer Token — valinnainen todennuksen kytkin ja tokenin näyttö
• Providers — jokainen tuettu pilvi-AI-tarjoaja, kullakin rivillä Set API Key -painike

2. Lisää ensimmäinen API-avaimesi

1. Valitse mikä tahansa tarjoaja Providers-luettelosta (esimerkiksi OpenAI (ChatGPT))
2. Napsauta Get API key avataksesi tarjoajan konsolin selaimessasi ja luo tai kopioi avain
3. Napsauta saman rivin Set API Key -painiketta ja liitä arvo valintaikkunaan
4. Napsauta Save. Tilamerkintä vaihtuu vihreäksi Configured

3. Yhdistä asiakassovellus

Osoita mikä tahansa OpenAI-yhteensopiva asiakas proxyyn. Perus-URL on http://localhost:8421/<provider>/v1. Provider-segmentti valitsee, mihin pilveen pyyntö lähetetään.

# Esimerkki: OpenAI Python SDK osoitettuna proxyyn
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 oikeaa avainta. AIProxyServer liittää ylävirran tunnistetiedot pyyntöä välittäessään.

Käyttöliittymän yleiskatsaus

Proxy Server -paneeli

Bearer Token -paneeli

• Require Bearer Token authentication — valintaruutu, joka kytkee todennuksen päälle tai pois. Oletuksena pois päältä helppoa paikallista käyttöä varten.
• Token field — nykyisen tokenin vain luku -näyttö. Näytetään pisteinä; käytä Copy saadaksesi sen.
• Regenerate — luo uusi satunnainen token. Olemassa olevat asiakkaat on päivitettävä uudella arvolla.

Providers-paneeli

Yksi rivi kutakin tuettua pilvitarjoajaa kohden. Jokainen rivi näyttää:

• Näyttönimen (esimerkiksi Claude (Anthropic))
• Konfigurointitila — vihreä Configured kun API-avain on tallennettu, muuten harmaa Not configured
• URL-polun jota asiakkaasi käyttävät, esim. /anthropic/v1/chat/completions
• Set API Key — avaa valintaikkunan tunnistetietojen syöttämistä varten
• Get API key — avaa tarjoajan konsolin selaimessasi

Tuetut tarjoajat

Yhdentoista pilvi-AI-palvelu on mukana paketissa. Useimmat käyttävät OpenAI Chat Completions -muotoa natiivisti ja välitetään sellaisenaan. Kolme (Anthropic, Gemini, ERNIE) puhuu omia protokolliaan; AIProxyServer kääntää pyynnöt ja vastaukset lennossa, jotta asiakkaasi näkee aina vain OpenAI-muodot.

Tarjoajakohtaiset huomautukset

• Azure OpenAI — liitä koko deployment-päätepiste Endpoint Base URL -kenttään, esimerkiksi https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Proxy 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 välimuistittaa pääsytokenit taustalla.
• Gemini — todennus tapahtuu URL-kyselyparametrin avulla; proxy lisää sen puolestasi. Ilmaistason minuuttikohtaiset kiintiöt pätevät edelleen.

API-viittaus

Päätepisteet

Suoratoisto

Kun asiakas lähettää "stream": true, proxy vastaa Server-Sent Events -viesteillä OpenAI:n 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 suoratoistot käännetään tähän muotoon, jotta kaikki asiakkaat voivat käyttää yhtä jäsentäjää.

Todennusotsake

Kun Require Bearer Token authentication on päällä, lähetä pääikkunan token jokaisen pyynnön mukana:

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

Asetukset

Avaa Settings-ikkuna alapalkin ratasikonista.

Asiakasesimerkit

cURL

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

# Claude saman OpenAI-muodon kautta
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",  # ohitetaan kun Bearer Token on pois päältä
)
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

// Minkä tahansa OpenAI-yhteensopivan Dart-asiakkaan käyttö
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // käyttämättä kun Bearer Token on pois päältä
);

Vinkkejä

• Pidä Bearer Token pois päältä kehittäessäsi paikallisesti; ota se päälle siinä hetkessä, kun otat LAN-pääsyn käyttöön.
• Käytä asiakaskoodissasi erillisiä Base-URL-osoitteita tarjoajakohtaisesti, niin voit vaihtaa tarjoajaa muuttamalla yhtä vakiota.
• Proxy käynnistyy automaattisesti, mutta voit pysäyttää sen tilapäisesti pääikkunasta, jos porttiristiriitoja syntyy.
• Jos tarjoajan ilmaistaso rajoittaa nopeuttasi, ylävirran virheilmoitus välitetään sanatarkasti. Mitään uudelleenyrityslogiikkaa ei piiloteta asiakkaalta.
• /v1/providers-päätepiste on hyödyllinen tarjoajien selvittämiseen suorituksen aikana.

Vianmääritys

Proxy ei käynnisty

• Toinen prosessi voi jo käyttää porttia 8421. Vaihda portti Settings-ikkunassa ja käynnistä proxy uudelleen.
• Tarkista järjestelmälokista käynnistyshetkellä näytetty virheilmoitus.

Pyyntö palauttaa 401 Unauthorized

• Bearer Token -vaatimus on päällä, mutta asiakas ei lähettänyt vastaavaa Authorization: Bearer ... -otsaketta.
• Tarjoajan oma API-avain saattaa olla virheellinen — ylävirran virhe välitetään, joten tarkista viestin runko.

Pyyntö palauttaa "API key is not configured"

• Avaa Providers-luettelo ja napsauta Set API Key kyseiselle tarjoajalle.
• ERNIE vaatii sekä API Keyn että Secret Keyn täyttämisen. Azure OpenAI vaatii myös Endpoint Base URL -kentän.

Mobiililaite ei tavoita proxyä

• Ota Allow LAN Access käyttöön Settings-ikkunassa.
• Käytä Base URL -kentässä näkyvää LAN-IP:tä, ei localhost-osoitetta.
• Varmista, että molemmat laitteet ovat samassa Wi-Fi-verkossa ja että palomuurisi sallii saapuvat yhteydet proxyn porttiin.

Suoratoiston vastaukset saapuvat kerralla

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

Yksityisyys

• API-avaimet tallennetaan salattuina Fernetillä polkuun ~/Library/Application Support/AIProxyServer/credentials.enc. Tiedoston master.key salausavaimella on 0600-oikeudet.
• Bearer Token, kun käytössä, tallennetaan myös vain salattuun holviin eikä koskaan kirjoiteta tavalliseen asetustiedostoon.
• Proxy välittää pyyntöjä vain niille tarjoajille, jotka olet erikseen konfiguroinut. Se ei tee mitään muita lähteviä kutsuja.
• Ei telemetriaa, ei analytiikkaa, ei kaatumisraportointia.
• Oletusverkkositouma on vain 127.0.0.1. LAN-altistus on opt-in.
• Keskustelujen sisältöjä ei tallenneta. AIProxyServer välittää tavuja ja unohtaa ne välittömästi.