Entegrasyon Rehberi

Bu rehber, Qevron'u uygulamanıza sıfırdan, adım adım entegre etmenizi sağlar: kurulumdan ilk çağrıya, oradan da üretime (production) hazır bir kuruluma kadar. Hiçbir adımı atlamadan ilerleyebilirsiniz.

Ön koşullar

Başlamadan önce elinizde şunlar olmalı:

Gereksinim	Açıklama
Qevron API anahtarı	sk- ile başlayan anahtar. Yoksa Kimlik Doğrulama sayfasından oluşturun.
Bir programlama dili	Bu rehberde Python ve JavaScript örnekleri var. curl ile dilden bağımsız da ilerleyebilirsiniz.
Temel terminal bilgisi	Komut çalıştırma, ortam değişkeni ayarlama.

Base URL her örnekte aynıdır: https://app.qevron.ai/v1

---

Adım 1 — Anahtarı al ve güvenli sakla

API anahtarı bir şifre gibidir. Asla kaynak koduna yazmayın; bir ortam değişkeninde saklayın.

macOS / Linux

export QEVRON_API_KEY="sk-..."

Windows (PowerShell)

$Env:QEVRON_API_KEY = "sk-..."

.env dosyası

# .env  (bu dosyayı .gitignore'a ekleyin!)
QEVRON_API_KEY=sk-...

WARNING

Anahtarı tarayıcı/mobil uygulama gibi istemci tarafına koymayın — herkes görebilir. İstekleri her zaman kendi sunucunuz üzerinden geçirin (bkz. Adım 7).

---

Adım 2 — SDK'yı kur

Qevron OpenAI uyumlu olduğu için resmi openai SDK'sını kullanırsınız.

Python

pip install openai

JavaScript

npm install openai

curl kullanacaksanız kuruluma gerek yok.

---

Adım 3 — İstemciyi yapılandır

Tek fark base_url: OpenAI yerine Qevron'a yönlendirin.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QEVRON_API_KEY"],
    base_url="https://app.qevron.ai/v1",
)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QEVRON_API_KEY,
  baseURL: "https://app.qevron.ai/v1",
});

---

Adım 4 — İlk çağrı ve yanıtı okuma

Python

resp = client.chat.completions.create(
    model="verinova",
    messages=[{"role": "user", "content": "Merhaba! Bir cümleyle kendini tanıt."}],
)
print(resp.choices[0].message.content)   # yanıt metni
print(resp.usage.total_tokens)           # harcanan token

JavaScript

const resp = await client.chat.completions.create({
  model: "verinova",
  messages: [{ role: "user", content: "Merhaba! Bir cümleyle kendini tanıt." }],
});
console.log(resp.choices[0].message.content);
console.log(resp.usage.total_tokens);

curl

curl https://app.qevron.ai/v1/chat/completions \
  -H "Authorization: Bearer $QEVRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"verinova","messages":[{"role":"user","content":"Merhaba!"}]}'

Yanıt metni choices[0].message.content, kullanım bilgisi usage içindedir. Hangi modellerin mevcut olduğunu görmek için /v1/models kullanın.

---

Adım 5 — Akış (streaming) ekle

Sohbet arayüzleri için yanıtı kelime kelime gösterin:

Python

stream = client.chat.completions.create(
    model="verinova",
    messages=[{"role": "user", "content": "Üç maddede RAG anlat."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

JavaScript

const stream = await client.chat.completions.create({
  model: "verinova",
  messages: [{ role: "user", content: "Üç maddede RAG anlat." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}

Ayrıntı: Akış (Streaming).

---

Adım 6 — Hata yönetimi ve yeniden deneme

Qevron, kanal düzeyinde otomatik failover yapar (bir sağlayıcı düşerse diğerine geçer). Yine de istemci tarafında geçici hataları (429, 5xx) üstel geri çekilme (exponential backoff) ile yeniden denemek iyi bir pratiktir.

import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(api_key=os.environ["QEVRON_API_KEY"], base_url="https://app.qevron.ai/v1")

def chat_with_retry(messages, model="verinova", max_retries=4):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except APIStatusError as e:
            # 429 (hız limiti) ve 5xx yeniden denenebilir; 4xx (örn. 401/404) denenmez
            if e.status_code in (429, 500, 502, 503) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)   # 1s, 2s, 4s, 8s
                continue
            raise
        except APIConnectionError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

print(chat_with_retry([{"role": "user", "content": "selam"}]).choices[0].message.content)

Hata kodlarının tam listesi: Hatalar.

---

Adım 7 — Üretim (prod) kontrol listesi

Canlıya çıkmadan önce:

• [ ] Anahtarı sunucuda tutun. Tarayıcı/mobilden doğrudan çağrı yapmayın; isteği kendi backend'iniz üzerinden proxy'leyin.
• [ ] Gizli yönetimi. Anahtarı ortam değişkeni / secret manager'da saklayın, depoya commit etmeyin.
• [ ] Model seçimini dinamik yapın. Model adlarını sabit yazmak yerine /v1/models ile mevcut olanları doğrulayın.
• [ ] Hız limitlerini izleyin. Yanıt başlıklarındaki X-RateLimit-* değerlerini takip edip gerekirse yavaşlayın (bkz. API Anahtarları ve Kota).
• [ ] Yeniden deneme mantığı ekleyin (Adım 6).
• [ ] Kullanımı izleyin. Her yanıttaki usage veya billing uç noktaları ile maliyeti takip edin.
• [ ] Zaman aşımı ayarlayın; uzun isteklerde (görsel/video) makul timeout verin.

---

AI ajanları ve araçlar için

Bu dokümantasyonun tamamına render etmeden, ham markdown olarak ulaşabilirsiniz — bir AI asistanına veya IDE'ye beslemek için:

# Tek sayfa: URL sonuna .md ekleyin
curl https://docs.qevron.ai/api/chat.md

# Tüm dokümanlar tek dosyada
curl https://docs.qevron.ai/llms-full.txt

Ayrıntı: API Genel Bakış — Ham markdown erişimi.

---

Sıradaki adımlar

İlk Sohbet Botu

Geçmişi hatırlayan, akışlı bir bot kurun.

RAG: Embedding + Rerank

Kendi dokümanlarınızla doğru yanıtlar.

API Referansı

Tüm uç noktalar ve gerçek şemalar.

OpenAI Uyumluluğu

Mevcut kodu Qevron'a taşıyın.