Skip to main content

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:

KaedahTujuan
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
StreamHandlerTerjemahan 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​

  1. Cipta penyesuai — pkg/provider/<name>.go yang melaksanakan Provider dengan kesemua 6 kaedah.
  2. Daftar dalam kilang — tambah kes dalam New(name) → memulangkan penyesuai anda.
  3. Kemas kini kekangan DB — jalankan migrasi yang menambah jenis baharu ke chk_provider.
  4. Tambah ke UI pentadbir — CRUD model sudah menerima medan provider; tiada perubahan kod diperlukan.
  5. Tulis ujian — TranslateRequest, TranslateResponse, ParseUsage, StreamHandler bagi setiap jenis peristiwa.
  6. Ujian integrasi — hujung ke hujung melalui pkg/testutil/mock<name> (lihat di bawah).
  7. Tambah harga — kembangkan jadual pkg/pricing/pricing.go dengan kunci "provider:model".

Corak terjemahan​

Pengendalian mesej sistem​

PenyediaLokasi sistem
OpenAIDi dalam messages[] sebagai {role:"system", content:"..."}
AnthropicMedan system peringkat atas (rentetan atau tatasusunan dengan cache_control)
GeminisystemInstruction: {parts:[...]} dalam badan permintaan

Format alat​

PenyediaMedan skemaPengisytiharan fungsi
OpenAIparameters (JSON Schema)function di dalam tools[]
Anthropicinput_schema (JSON Schema)input_schema + name/description dalam tools[]
GeminiN/AfunctionDeclarations[] dalam contents

Pemetaan peristiwa penstriman​

PenyediaPeristiwa natifSetara ketulan OpenAI
Anthropicmessage_start{choices:[{delta:{role:"assistant", content:""}}]}
Anthropiccontent_block_delta (teks){choices:[{delta:{content:"..."}}]}
Anthropicmessage_stopdata: [DONE]\n\n
Anthropicerrorperistiwa 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.message dan error.type
  • Siasatan kesihatan: endpoint /health atau /v1/models penyedia ialah sasaran semakan kesihatan yang sah
  • Jadual harga dikemas kini dalam pkg/pricing/pricing.go dengan 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-31 ditambah secara automatik oleh PrepareRequest
  • Token cache dihuraikan dalam ParseUsage dan dibilkan secara berasingan melalui ComputeCost dalam pkg/pricing/