Panduan Integrasi Penyedia
Gambaran keseluruhan
Yabanin mengabstrakkan API LLM huluan di sebalik antara muka provider.Provider (pkg/provider/provider.go). Setiap penyedia menyokong lima operasi:
| Kaedah | Tujuan |
|---|---|
Name() | Pengecam kanonikal ("openai", "anthropic", "custom") |
Path(stream bool) | Laluan endpoint HTTP (/v1/chat/completions atau /v1/messages) |
PrepareRequest(ctx, baseURL, path, body, apiKey, stream) | Menetapkan URL, pengepala (Auth, versi, beta), jenis kandungan |
TranslateRequest(openaiBody) | JSON OpenAI → skema natif penyedia |
TranslateResponse(providerBody) | JSON natif penyedia → bentuk OpenAI ChatCompletion |
ParseUsage(respBody) | Mengeluarkan token prompt/completion/cache |
StreamHandler | Terjemahan SSE masa nyata (melalui pkg/provider/stream.go) |
Kilang penyesuai (pkg/provider/factory.go) menyelesaikan nama penyedia pada masa jalan melalui New(name). Kolam huluan (pkg/upstream/pool.go) mencipta satu *Client bagi setiap pasangan (provider, URL), masing-masing membawa penyesuai sendiri.
Pelan Pengekodan Z.AI GLM (zai-coding)
Penyesuai Pelan Pengekodan serasi OpenAI yang dipin ke https://api.z.ai/api/coding/paas/v4. Dayakan dengan YABANIN_ZAI_CODING_ENABLED=true. Daftarkan model seperti glm-5.3 dengan provider: zai-coding; upstream_url diabaikan supaya kuota tidak boleh bocor ke PAYG atau hos arbitrari. Bendera ciri dimatikan secara lalai. Contoh OpenCode: examples/opencode.json.
Menambah penyedia baharu
- Cipta penyesuai —
pkg/provider/<name>.goyang melaksanakanProviderdengan kesemua 6 kaedah. - Daftar dalam kilang — tambah kes dalam
New(name)→ memulangkan penyesuai anda. - Kemas kini kekangan DB — jalankan migrasi yang menambah jenis baharu ke
chk_provider. - Tambah ke UI pentadbir — CRUD model sudah menerima medan
provider; tiada perubahan kod diperlukan. - Tulis ujian — TranslateRequest, TranslateResponse, ParseUsage, StreamHandler bagi setiap jenis peristiwa.
- Ujian integrasi — hujung ke hujung melalui
pkg/testutil/mock<name>(lihat di bawah). - Tambah harga — kembangkan jadual
pkg/pricing/pricing.godengan kunci"provider:model".
Corak terjemahan
Pengendalian mesej sistem
| Penyedia | Lokasi sistem |
|---|---|
| OpenAI | Di dalam messages[] sebagai {role:"system", content:"..."} |
| Anthropic | Medan system peringkat atas (rentetan atau tatasusunan dengan cache_control) |
| Gemini | systemInstruction: {parts:[...]} dalam badan permintaan |
Format alat
| Penyedia | Medan skema | Pengisytiharan fungsi |
|---|---|---|
| OpenAI | parameters (JSON Schema) | function di dalam tools[] |
| Anthropic | input_schema (JSON Schema) | input_schema + name/description dalam tools[] |
| Gemini | N/A | functionDeclarations[] dalam contents |
Pemetaan peristiwa penstriman
| Penyedia | Peristiwa natif | Setara ketulan OpenAI |
|---|---|---|
| Anthropic | message_start | {choices:[{delta:{role:"assistant", content:""}}]} |
| Anthropic | content_block_delta (teks) | {choices:[{delta:{content:"..."}}]} |
| Anthropic | message_stop | data: [DONE]\n\n |
| Anthropic | error | peristiwa ralat dengan mesej |
Senarai semak ujian untuk penyedia baharu
- TranslateRequest meliputi: sistem, perbualan berbilang pusingan, penggunaan alat, kandungan berstruktur, blok cache_control
- TranslateResponse: satu pilihan, berbilang pilihan (jika disokong), seksyen penggunaan
- ParseUsage: prompt_tokens, completion_tokens, total, cache_read, cache_creation — semuanya diambil kira
- StreamHandler: setiap jenis peristiwa natif diterjemahkan ke ketulan SSE OpenAI + penamatan
[DONE] - Ujian integrasi dengan pelayan olok (
pkg/testutil/mock<name>) — respons 200 hujung ke hujung melalui gerbang - Pemetaan ralat integrasi: ralat 4xx → bentuk ralat OpenAI yang betul dengan
error.messagedanerror.type - Siasatan kesihatan: endpoint
/healthatau/v1/modelspenyedia ialah sasaran semakan kesihatan yang sah - Jadual harga dikemas kini dalam
pkg/pricing/pricing.godengan kadar semasa bagi setiap juta token
Corak pelayan olok
Gunakan pkg/testutil/mockopenai atau pkg/testutil/mockanthropic untuk ujian integrasi:
srv := mockopenai.New()
ts := httptest.NewServer(srv)
defer ts.Close()
// Configure response
srv.SetResponse(200, `{"id":"test","choices":[...]}`)
// Or simulate rate-limiting then success
srv.FailFirstN(2, 429, "rate limited")
srv.SetResponse(200, `{"id":"ok","choices":[...]}`)
// For streaming endpoints
srv.SetStreamMode(true)
srv.SetResponse(200, `{"delta":{"content":"Hello"}}\n\n`)
// Verify what was sent
recs := srv.Requests() // []Request with Method, URL, Header, Body, Path
assert.Equal(t, "my-key", recs[0].Header.Get("Authorization"))
Corak yang sama terpakai pada mockanthropic — gunakan MessagesJSON() atau MessagesJSONWithCache() untuk badan respons.
Cache prompt
Untuk penyedia yang menyokong cache prompt (Anthropic):
- Penyesuai mengesan kunci
"cache_control"dalam blok kandungan mesej - Apabila hadir, pengepala
anthropic-beta: prompt-caching-2024-07-31ditambah secara automatik olehPrepareRequest - Token cache dihuraikan dalam
ParseUsagedan dibilkan secara berasingan melaluiComputeCostdalampkg/pricing/