beyhan/opantoantro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aa6dbfefb3209862df25d7dc07e1736ac38f9cad
opantoantro/PROJE_PROMOSIYON_PROMPT.md
T
Beyhan Ogur a408821410 first commit
2026-05-11 15:08:50 +03:00

8.4 KiB
Raw Blame History

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:

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:

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

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.

Reference in New Issue View Git Blame Copy Permalink