Beyhan Ogur
228 lines
8.4 KiB
Markdown
228 lines
8.4 KiB
Markdown
# LLM Gateway / Proxy Projesi - Geliştirici İş Emri (Türkçe)
|
||
|
||
Bu doküman, bir geliştiriciye veya yapay zeka asistanına verilip projeyi tamamen uygulattıracak detaylı iş emridir. Hedef: Go + Fiber v3 tabanlı bir servis geliştirmek; OpenAI-compat ve Anthropic-compat proxy/gateway, Bifrost mapping, PostgreSQL (GORM) entegrasyonu, Swagger dokümanları ve Docker destekli dağıtım.
|
||
|
||
---
|
||
|
||
## Özet Hedefler
|
||
- OpenAI-uyumlu istekleri alın, hedef backend: `https://api.deepseek.com`.
|
||
- Anthropic-uyumlu istekleri alın, hedef backend: `https://api.deepseek.com/anthropic` veya (konfigürasyona bağlı olarak) Bifrost (`http://10.80.80.70:8080/v1`).
|
||
- Lokalde Anthropic endpoint'i: `http://localhost:8000/anthropic` (Bifrost mapping).
|
||
- Kullanılacak kütüphaneler:
|
||
- `github.com/gofiber/fiber/v3`
|
||
- `gorm.io/gorm`
|
||
- `gorm.io/driver/postgres`
|
||
|
||
---
|
||
|
||
## Çalışma Ortamı / Gereksinimler
|
||
- Go modül yapısı (go1.20+ önerilir).
|
||
- PostgreSQL veritabanı (docker-compose ile sağlanabilir).
|
||
- Docker & docker-compose (opsiyonel ama önerilir).
|
||
- İstenen `go get` komutları (README'de gösterilecek):
|
||
- `go mod download` (tüm bağımlılıklar go.mod'da tanımlı)
|
||
- `go get -u gorm.io/gorm`
|
||
- `go get -u gorm.io/driver/postgres`
|
||
|
||
---
|
||
|
||
## Konfigürasyon (Environment Variables)
|
||
- `PORT` (default: `8000`)
|
||
- `OPENAI_BACKEND` (default: `https://api.deepseek.com`) ##Örnek
|
||
- `ANTHROPIC_BACKEND` (default: `https://api.deepseek.com/anthropic`)##Örnek
|
||
- `USE_BIFROST_FOR_ANTHROPIC` (`true`/`false`) — `true` ise Anthropic çağrıları `BIFROST_URL`'e yönlendirilir
|
||
- `BIFROST_URL` (örnek: `http://10.80.80.70:8080/v1`)##Örnek
|
||
- `POSTGRES_DSN` (örnek: `host=localhost user=app password=pass dbname=app port=5432 sslmode=disable TimeZone=UTC`)##Örnek
|
||
- `REQUEST_TIMEOUT_SECONDS` (ör: `30`)##Örnek
|
||
|
||
Örnek `.env.example`:
|
||
```env
|
||
PORT=8000
|
||
OPENAI_BACKEND=https://api.deepseek.com
|
||
ANTHROPIC_BACKEND=https://api.deepseek.com/anthropic
|
||
BIFROST_URL=http://10.80.80.70:8080/v1
|
||
USE_BIFROST_FOR_ANTHROPIC=true
|
||
POSTGRES_DSN=host=postgres user=app password=pass dbname=app port=5432 sslmode=disable TimeZone=UTC
|
||
REQUEST_TIMEOUT_SECONDS=30
|
||
```
|
||
|
||
---
|
||
|
||
## API Endpoint Gereksinimleri
|
||
|
||
### OpenAI-uyumlu
|
||
- `POST /v1/chat/completions` -> forward to `${OPENAI_BACKEND}/v1/chat/completions`
|
||
- `POST /v1/completions` -> forward to `${OPENAI_BACKEND}/v1/completions`
|
||
- Tüm `/v1/*` OpenAI endpoint'leri generic olarak hedef backend'e yönlendirilmeli (method korunacak).
|
||
|
||
Kurallar:
|
||
- Authorization header (Bearer ...) ve diğer önemli header'lar hedefe iletilecek.
|
||
- Body genelde olduğu gibi POST edilecek.
|
||
- Hedeften gelen status code ve body olduğu gibi client'a iletilecek.
|
||
- Hedefe ulaşılamazsa 502 döndürülecek.
|
||
|
||
### Anthropic-uyumlu
|
||
- `POST /anthropic/*` (ör. `/anthropic/complete`) -> eğer `USE_BIFROST_FOR_ANTHROPIC=false` ise `${ANTHROPIC_BACKEND}`'e, `true` ise `${BIFROST_URL}`'e yönlendir.
|
||
- Eğer Bifrost formatı ile Anthropic formatı farklıysa, minimal bir dönüşüm fonksiyonu yazılmalı (request/response mapping).
|
||
|
||
Hata durumları:
|
||
- Hedefe ulaşılamaz veya hata alınırsa uygun HTTP kodu döndürülecek (502/504/500 gibi).
|
||
|
||
### Sağlık ve Dokümantasyon
|
||
- `GET /health` -> servis, DB ve opsiyonel hedef backendlere temel sağlık bilgisi dönecek.
|
||
- Swagger UI: `/swagger/*` (Fiber v3 native HTML + CDN Swagger UI ile sunulacak).
|
||
|
||
---
|
||
|
||
## İstek / Yanıt İşleme
|
||
- Timeout yönetimi (env'den): `REQUEST_TIMEOUT_SECONDS`.
|
||
- Retries (opsiyonel): tercih halinde `github.com/hashicorp/go-retryablehttp` veya benzeri kullanılabilir.
|
||
- İsteklerin DB'ye loglanması (Postgres + GORM) — minimal kayıt:
|
||
- timestamp, endpoint, method, client IP, model (varsa), tokens estimate (opsiyonel), response status, latency
|
||
- Büyük request body'leri truncation ile kaydedilecek (ör. 2000 karakter).
|
||
- Sensitive veriler (Authorization vb.) maskelenmeli, düz kaydedilmemeli.
|
||
|
||
---
|
||
|
||
## Veri Modeli (Minimal)
|
||
- `RequestLog`:
|
||
- ID (UUID / auto increment)
|
||
- CreatedAt
|
||
- Endpoint (string)
|
||
- Method (string)
|
||
- ClientIP (string)
|
||
- RequestBody (text, truncate)
|
||
- ResponseStatus (int)
|
||
- LatencyMs (int)
|
||
- GORM AutoMigrate ile migration sağlanacak.
|
||
|
||
---
|
||
|
||
## Proje Yapısı (Öneri)
|
||
- `main.go` (Fiber app, config yükleme, route register)
|
||
- `handlers/openai.go`
|
||
- `handlers/anthropic.go`
|
||
- `internal/proxy/proxy.go` (generic forwarder)
|
||
- `internal/transform/anthropic_bifrost.go` (dönüşüm fonksiyonları)
|
||
- `models/request_log.go`
|
||
- `config/config.go` (env yükleme)
|
||
- `docker/Dockerfile`
|
||
- `docker/docker-compose.yml`
|
||
- `README.md`
|
||
- `tests/*` (unit test örnekleri)
|
||
- `go.mod`, `go.sum`
|
||
|
||
---
|
||
|
||
## Swagger
|
||
- Fiber v3 native HTML handler + CDN Swagger UI ile `/swagger/*` altında UI sunulacak.
|
||
- En az OpenAI-compatible `chat/completions` ve Anthropic endpoint'leri için örnek request/response gösterilecek.
|
||
|
||
---
|
||
|
||
## Docker & docker-compose
|
||
- Multi-stage `Dockerfile` (build + runtime).
|
||
- `docker-compose.yml`:
|
||
- `app` servisi (build)
|
||
- `postgres` servisi (resmi image, örnek env)
|
||
- `docker-compose` ile test sağlanabilecek (izole ortam).
|
||
|
||
---
|
||
|
||
## Testler
|
||
- Unit test: OpenAI proxy handler için en az iki test:
|
||
- başarılı forward (mock backend ile)
|
||
- hedef hata verdiğinde uygun hata dönüşü
|
||
- Integration test (opsiyonel): docker-compose altında mocked backend'e karşı örnek.
|
||
|
||
---
|
||
|
||
## Komutlar / Kurulum (README'de belirtilecek)
|
||
- `go mod init github.com/<you>/<repo>`
|
||
- `go mod download` (fiber v3 ve diğer bağımlılıklar go.mod'da)
|
||
- `go get -u gorm.io/gorm`
|
||
- `go get -u gorm.io/driver/postgres`
|
||
- `go build ./...`
|
||
- `docker build -t llm-gateway:latest .`
|
||
- `docker-compose up -d`
|
||
|
||
---
|
||
|
||
## Örnek curl Çağrıları
|
||
|
||
OpenAI compatible:
|
||
```bash
|
||
curl -X POST "http://localhost:8000/v1/chat/completions" \
|
||
-H "Authorization: Bearer $OPENAI_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'
|
||
```
|
||
|
||
Anthropic (lokal mapped to Bifrost veya deepseek):
|
||
```bash
|
||
curl -X POST "http://localhost:8000/anthropic/complete" \
|
||
-H "Authorization: Bearer $ANTHROPIC_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"prompt":"Say hello", "max_tokens": 64}'
|
||
```
|
||
|
||
---
|
||
|
||
## Teslim Edilecekler (Repository içinde)
|
||
- `main.go`
|
||
- `handlers/openai.go`
|
||
- `handlers/anthropic.go`
|
||
- `internal/proxy/proxy.go`
|
||
- `internal/transform/anthropic_bifrost.go`
|
||
- `models/request_log.go`
|
||
- `config/config.go`
|
||
- `docker/Dockerfile`
|
||
- `docker/docker-compose.yml`
|
||
- `README.md` (kurulum, env örnekleri, docker-compose, curl örnekleri)
|
||
- `tests/*` (unit testler)
|
||
- `go.mod`, `go.sum`
|
||
|
||
---
|
||
|
||
## Kabul Kriterleri (Acceptance Criteria)
|
||
- `/v1/*` istekleri `OPENAI_BACKEND`'e başarılı yönleniyor.
|
||
- `/anthropic/*` istekleri `USE_BIFROST_FOR_ANTHROPIC` konfigürasyonuna göre `BIFROST_URL` veya `ANTHROPIC_BACKEND`'e gidiyor.
|
||
- İstekler DB'ye loglanıyor (Postgres çalışırken).
|
||
- Swagger UI erişilebilir (`/swagger/*`).
|
||
- README yönergelerine göre proje çalıştırılabiliyor.
|
||
- En az 1 birim testi geçiyor (`go test ./...`).
|
||
|
||
---
|
||
|
||
## Teknik Notlar / İpuçları
|
||
- HTTP client: `net/http` + `context` (timeout) veya tercih edilirse fiber'ın client'ı.
|
||
- Retries: isteğe bağlı; `go-retryablehttp` önerilir.
|
||
- Büyük body'leri DB'ye kaydederken truncate et (ör. 2000 char).
|
||
- Sensitive alanlar maskelenmeli.
|
||
- Anthropic <-> Bifrost dönüşümleri karmaşıksa, minimal mapping uygula ve README'de açıkla.
|
||
- Environment swap ile Deepseek <-> Bifrost kolayca değiştirilebilmeli.
|
||
|
||
---
|
||
|
||
## Geliştirme Adımları (Öneri Sırayla)
|
||
1. Repo skeleton oluştur (go mod init, klasör yapısı).
|
||
2. `config/config.go`: env yükleme ve default ayarlar.
|
||
3. `main.go`: Fiber app init, DB bağlantısı (GORM), AutoMigrate, route register.
|
||
4. `internal/proxy/proxy.go`: generic forwarder implementasyonu (timeout, header forwarding).
|
||
5. `handlers/openai.go` & `handlers/anthropic.go`: handler'ları yaz, DB logging çağrılarını ekle.
|
||
6. Basit Swagger dokümantasyonu ekle.
|
||
7. Dockerfile & docker-compose ekle.
|
||
8. Unit testleri yaz ve çalıştır.
|
||
9. README güncelle, örnek env ve curl'leri ekle.
|
||
|
||
---
|
||
|
||
## İletişim / Teslim
|
||
- Repo URL veya zip ile teslim.
|
||
- README ile çalıştırma adımları.
|
||
- Örnek curl komutları ve `.env.example`.
|
||
- (Opsiyonel) Dönüşümlere dair kısa açıklama ve input/output örnekleri.
|
||
|
||
---
|
||
|
||
Eğer bu prompt'u doğrudan bir geliştiriciye/assistant'e vereceksen bu dosyayı kullan. İstersen ben bu prompt'u kullanarak ilk adımda repository skeleton'ını ve `main.go` + temel proxy handler'ı oluşturmaya başlayabilirim — başlamak istersen sadece "başla" de. |