evren-sdk

EVREN Yapay Zeka Platformu — Resmi Python SDK

Türkçe · English · Examples · Changelog

🇹🇷 Türkçe

EVREN Yapay Zeka Platformu'nun resmi Python SDK'sı: platformda eğitilmiş bilgisayarlı görü modelleriyle çıkarım ve EVREN LLM geçidi (sohbet, akış, embedding, rerank).

Nesne tespiti · Sınıflandırma · Segmentasyon · OBB · Keypoint · Edge Inference · LLM Geçidi

Mimari

graph LR
    SDK["🐍 Python SDK"] -->|HTTPS / TLS| GW["⚡ FastAPI Gateway"]
    GW -->|gRPC| TS["🔮 Triton Server"]
    TS --- GPU["🖥️ 8× A6000 GPU"]
    SDK -.->|Edge Mode| DEV["📷 Lokal Cihaz\nWebcam / RTSP / Video"]

    subgraph EVREN Inference Cluster
        GW
        TS
        GPU
    end

Tek bir predict() cagrisi arkasinda 8× NVIDIA A6000 GPU calisiyor. Kullanici altyapi yonetmez — pip install ve 3 satir kod yeter.

Kurulum

pip install evren-sdk            # temel SDK
pip install evren-sdk[edge]      # + OpenCV (kamera/video)

Hızlı Başlangıç

from evren_sdk import EvrenClient

client = EvrenClient(api_key="evren_xxxxx")
result = client.predict("kullanici/model-adi", "foto.jpg", confidence=0.3)

for det in result.predictions:
    print(f"{det.class_name}: {det.confidence:.0%}  bbox={det.bbox}")

Daha fazla ornek icin examples/ dizinine bakin.

Kimlik Doğrulama

Platformda Ayarlar → API Anahtarları sayfasından anahtar oluşturun. Anahtar evren_ ön eki ile başlar.

client = EvrenClient(api_key="evren_xxxxx")    # API anahtarı (önerilen)
client = EvrenClient(api_key="eyJhbGci...")    # JWT token

Çıkarım Akışı

graph TD
    IMG["🖼️ Görsel\ndosya / Path / bytes"] --> P["predict()\nconfidence, iou, image_size"]
    P --> PR["PredictResult\n.count  .inference_ms  .predictions[]"]
    PR --> F["filter()"]
    PR --> E["to_yolo() · to_coco() · to_csv()"]
    PR --> S["save()\n.json  .csv  .txt"]

Tekil Çıkarım

result = client.predict(
    model="kullanici/model-adi",        # slug, slug:tag veya UUID
    image="resim.jpg",                  # dosya yolu, Path veya bytes
    confidence=0.25,
    iou=0.45,
    image_size=640,
    classes=["araba", "insan"],         # isteğe bağlı
)

Toplu Çıkarım (Batch)

batch = client.predict_batch(
    model="kullanici/model-adi",
    images=["img1.jpg", "img2.jpg", "img3.jpg"],
    confidence=0.3,
)

for r in batch:
    print(f"{r.count} tespit, {r.inference_ms:.0f} ms")

Bkz. examples/02_batch_inference.py

Sonuç İşleme & Export

result = client.predict("kullanici/model", "sahne.jpg")

# filtrele
filtre = result.filter(min_confidence=0.5, classes=["araba"])

# export
result.to_yolo()          # YOLO txt format
result.to_coco()          # COCO dict list
result.to_csv()           # CSV string

# dosyaya kaydet (format uzantıdan anlaşılır)
result.save("sonuc.json")
result.save("sonuc.csv")
result.save("labels.txt")

Detay: examples/03_result_export.py

Model Bilgileri & Warmup

# sınıfları listele
info = client.model_classes("kullanici/model-adi")
for cls in info.classes:
    print(f"  {cls.name}: {cls.color}")

# mevcut modelleri listele
for m in client.list_models():
    print(f"{m.full_slug} — {m.architecture}")

# GPU'ya ön-yükleme (cold-start elimine)
client.warmup(["kullanici/model-adi"])

Performans Testi

bench = client.benchmark("kullanici/model", "test.jpg", rounds=20)

print(f"Avg: {bench.avg_ms:.1f}ms  |  p95: {bench.p95_ms:.1f}ms")
print(f"Min: {bench.min_ms:.1f}ms  |  Max: {bench.max_ms:.1f}ms")
print(f"Throughput: {bench.throughput_fps:.1f} FPS")

→ examples/04_benchmark.py

Model İndirme

path = client.download_model("kullanici/model", output="weights/", fmt="onnx")
print(f"Kaydedildi: {path}")   # weights/best.onnx

Veri Setine Görsel Yükleme

SDK üzerinden doğrudan bir veri setine görsel yükleyebilirsiniz.

resp = client.upload_to_dataset(dataset_id="<UUID>", image="yeni_gorsel.jpg")

Asenkron Kullanım

import asyncio
from evren_sdk import AsyncEvrenClient

async def main():
    async with AsyncEvrenClient(api_key="evren_xxxxx") as client:
        result = await client.predict("kullanici/model", "foto.jpg")
        batch  = await client.predict_batch("kullanici/model", ["a.jpg", "b.jpg"])

asyncio.run(main())

Paralel pipeline icin examples/07_async_pipeline.py

LLM Geçidi (Sohbet, Akış, Embedding, Rerank)

EvrenLLMClient, EVREN LLM geçidine (evren-llmapi.ssyz.org.tr) bağlanır. Görü istemcisinden ayrıdır ve evren_llm_... ile başlayan LLM anahtarı kullanır. Anahtar verilmezse EVREN_LLM_API_KEY ortam değişkeninden okunur.

from evren_sdk import EvrenLLMClient

with EvrenLLMClient() as llm:                       # EVREN_LLM_API_KEY
    print(llm.list_models())

    r = llm.chat("glm-5.3", [{"role": "user", "content": "Merhaba"}], max_tokens=512)
    print(r.content)          # yanıt metni (hiçbir zaman None değildir)
    print(r.reasoning)        # düşünen modellerde düşünme metni
    print(r.usage)            # token kullanımı
    print(r.request_id)       # destek talebinde paylaşın

    # akış — yalnızca metin
    for parca in llm.chat_stream("deepseek-v4.1-flash", [{"role": "user", "content": "Bir şiir yaz"}]):
        print(parca, end="", flush=True)

    # akış — ayrıntılı: düşünme metni, araç çağrıları, son parçada kullanım
    for d in llm.stream("glm-5.3", [{"role": "user", "content": "2+2?"}]):
        if d.reasoning: ...
        if d.content: print(d.content, end="")
        if d.usage: print("\n", d.usage)

    vektorler = llm.embed("qwen3-embedding-8b", ["merhaba", "dünya"])
    sirali = llm.rerank("qwen3-reranker-8b", "Türkiye'nin başkenti",
                        ["Paris Fransa'dadır", "Ankara başkenttir"], top_n=1)

Araç çağrısı (function calling) OpenAI biçimiyle çalışır; sonuç r.tool_calls alanındadır:

tools = [{"type": "function", "function": {"name": "hava", "parameters": {
    "type": "object", "properties": {"sehir": {"type": "string"}}, "required": ["sehir"]}}}]
r = llm.chat("glm-5.3", [{"role": "user", "content": "Ankara'da hava nasıl?"}], tools=tools)
for call in r.tool_calls:
    print(call["function"]["name"], call["function"]["arguments"])

Güvenilirlik. 429, 502, 503, 504 ve bağlantı hatalarında istemci Retry-After başlığına uyarak otomatik tekrar dener (max_retries=2). Akışsız her çağrıya bir Idempotency-Key eklenir; tekrar denenen istek geçitte tekilleştirilir, çift çalıştırılmaz ve çift ücretlendirilmez. Akışlar yalnızca istek modele ulaşmadan reddedildiyse (429/503) tekrar denenir. Akış yarıda kesilirse LLMServiceError (code="stream_interrupted") fırlatılır; eksik yanıt tamamlanmış gibi dönmez.

from evren_sdk import EvrenLLMError, LLMRateLimitError

try:
    llm.chat("glm-5.3", mesajlar)
except LLMRateLimitError as e:
    print(e.retry_after, e.evren.get("resets_at"))
except EvrenLLMError as e:
    print(e.status_code, e.code, e.request_id, e.evren)

Asenkron kullanım için AsyncEvrenLLMClient aynı yüzeyi sunar (await llm.chat(...), async for parca in llm.chat_stream(...)).

Edge Modu (GPU'suz Cihazlar)

GPU olmayan cihazlarda (Raspberry Pi, laptop, endüstriyel PC) gerçek zamanlı çıkarım. Çıkarım EVREN GPU'larında çalışır — lokal deneyim hissi verir.

graph LR
    CAM["📷 Kamera\nWebcam / RTSP / Video"] -->|frame| EC["EvrenCamera\ncompress + send"]
    EC -->|HTTPS| GPU["🖥️ EVREN GPU\nCluster"]
    GPU -->|JSON| EC
    EC -->|render| CAM

pip install evren-sdk[edge]

from evren_sdk import EvrenCamera

cam = EvrenCamera("evren_...", "kullanici/model", confidence=0.3)

cam.run(0)                                      # webcam, ESC ile kapat
cam.record("input.mp4", "output.mp4")           # video isle + kaydet

for frame, result in cam.stream(0):             # kendi loop'unuz
    print(f"{result.count} tespit")

for path, result in cam.scan("images/"):        # klasör tarama
    print(f"{path.name}: {result.count} nesne")

Bkz. examples/05_edge_camera.py

Hata Yönetimi

from evren_sdk import (
    EvrenClient, InsufficientCreditsError,
    NotFoundError, RateLimitError, InferenceError,
)

client = EvrenClient(api_key="evren_xxxxx")

try:
    result = client.predict("kullanici/model", "test.jpg")
except InsufficientCreditsError as e:
    print(f"Kredi yetersiz — gerekli: {e.required}, bakiye: {e.available}")
except NotFoundError:
    print("Model bulunamadı")
except RateLimitError as e:
    time.sleep(e.retry_after)
except InferenceError:
    print("GPU sunucusu geçici olarak kullanılamıyor")

Her çıkarım kredi tüketir. Bakiye yetersizse SDK InsufficientCreditsError fırlatır — e.required ve e.available alanları bakiye bilgisini taşır.

API Referansı

🇬🇧 English

Official Python SDK of the EVREN AI Platform: inference on computer vision models trained on EVREN and access to the EVREN LLM gateway (chat, streaming, embeddings, rerank).

Object Detection · Classification · Segmentation · OBB · Keypoint · Edge Inference · LLM Gateway

Architecture

graph LR
    SDK["🐍 Python SDK"] -->|HTTPS / TLS| GW["⚡ FastAPI Gateway"]
    GW -->|gRPC| TS["🔮 Triton Server"]
    TS --- GPU["🖥️ 8× A6000 GPU"]
    SDK -.->|Edge Mode| DEV["📷 Local Device\nWebcam / RTSP / Video"]

    subgraph EVREN Inference Cluster
        GW
        TS
        GPU
    end

A single predict() call leverages 8× NVIDIA A6000 GPUs. No infrastructure management — pip install and 3 lines of code.

Installation

pip install evren-sdk            # core SDK
pip install evren-sdk[edge]      # + OpenCV (camera/video support)

Quick Start

from evren_sdk import EvrenClient

client = EvrenClient(api_key="evren_xxxxx")
result = client.predict("owner/model-name", "photo.jpg", confidence=0.3)

for det in result.predictions:
    print(f"{det.class_name}: {det.confidence:.0%}  bbox={det.bbox}")

See examples/ for runnable scripts covering every feature.

Authentication

Create an API key from Settings → API Keys on the platform. Keys start with the evren_ prefix.

client = EvrenClient(api_key="evren_xxxxx")    # API key (recommended)
client = EvrenClient(api_key="eyJhbGci...")    # JWT token

Inference Pipeline

graph TD
    IMG["🖼️ Image\nfile / Path / bytes"] --> P["predict()\nconfidence, iou, image_size"]
    P --> PR["PredictResult\n.count  .inference_ms  .predictions[]"]
    PR --> F["filter()"]
    PR --> E["to_yolo() · to_coco() · to_csv()"]
    PR --> S["save()\n.json  .csv  .txt"]

Single Prediction

result = client.predict(
    model="owner/model-name",           # slug, slug:tag, or UUID
    image="image.jpg",                  # file path, Path, or bytes
    confidence=0.25,
    iou=0.45,
    image_size=640,
    classes=["car", "person"],          # optional
)

Batch Prediction

batch = client.predict_batch(
    model="owner/model-name",
    images=["img1.jpg", "img2.jpg", "img3.jpg"],
    confidence=0.3,
)

for r in batch:
    print(f"{r.count} detections, {r.inference_ms:.0f} ms")

See examples/02_batch_inference.py

Result Processing & Export

result = client.predict("owner/model", "scene.jpg")

filtered = result.filter(min_confidence=0.5, classes=["car"])

result.to_yolo()          # YOLO txt
result.to_coco()          # COCO dict list
result.to_csv()           # CSV string

result.save("result.json")
result.save("result.csv")
result.save("labels.txt")

Full example: examples/03_result_export.py

Model Info & Warmup

info = client.model_classes("owner/model-name")
for cls in info.classes:
    print(f"  {cls.name}: {cls.color}")

for m in client.list_models():
    print(f"{m.full_slug} — {m.architecture}")

client.warmup(["owner/model-name"])   # eliminate cold-start

Benchmarking

bench = client.benchmark("owner/model", "test.jpg", rounds=20)

print(f"Avg: {bench.avg_ms:.1f}ms  |  p95: {bench.p95_ms:.1f}ms")
print(f"Throughput: {bench.throughput_fps:.1f} FPS")

→ examples/04_benchmark.py

Model Download

path = client.download_model("owner/model", output="weights/", fmt="onnx")
print(f"Saved to: {path}")   # weights/best.onnx

Upload to Dataset

Upload images to a dataset directly from the SDK.

resp = client.upload_to_dataset(dataset_id="<UUID>", image="new_image.jpg")

Async Usage

import asyncio
from evren_sdk import AsyncEvrenClient

async def main():
    async with AsyncEvrenClient(api_key="evren_xxxxx") as client:
        result = await client.predict("owner/model", "photo.jpg")
        batch  = await client.predict_batch("owner/model", ["a.jpg", "b.jpg"])

asyncio.run(main())

Parallel pipeline: examples/07_async_pipeline.py

LLM Gateway (Chat, Streaming, Embeddings, Rerank)

EvrenLLMClient talks to the EVREN LLM gateway (evren-llmapi.ssyz.org.tr). It is separate from the vision client and uses an LLM key starting with evren_llm_. If no key is passed, EVREN_LLM_API_KEY is used.

from evren_sdk import EvrenLLMClient

with EvrenLLMClient() as llm:
    r = llm.chat("glm-5.3", [{"role": "user", "content": "Hello"}], max_tokens=512)
    print(r.content, r.reasoning, r.usage, r.request_id)

    for chunk in llm.chat_stream("deepseek-v4.1-flash", [{"role": "user", "content": "Write a poem"}]):
        print(chunk, end="", flush=True)

    for d in llm.stream("glm-5.3", [{"role": "user", "content": "2+2?"}]):
        ...  # d.content, d.reasoning, d.tool_calls, d.finish_reason, d.usage

    vectors = llm.embed("qwen3-embedding-8b", ["hello", "world"])
    ranked = llm.rerank("qwen3-reranker-8b", "capital of Türkiye",
                        ["Paris is in France", "Ankara is the capital"], top_n=1)

Tool calls use the OpenAI format and are returned in r.tool_calls.

Reliability. On 429, 502, 503, 504 and connection errors the client retries automatically (max_retries=2), honouring Retry-After. Every non-streaming call carries an Idempotency-Key, so a retried request is de-duplicated by the gateway and never executed or billed twice. Streams are retried only when the gateway rejected them before reaching the model (429/503). An interrupted stream raises LLMServiceError (code="stream_interrupted") instead of silently returning a truncated answer. Errors expose status_code, code, param, request_id, retry_after and the EVREN-specific evren payload (resets_at, suggested_models, …).

AsyncEvrenLLMClient offers the same API with await / async for.

Edge Mode (GPU-free Devices)

Real-time inference on devices without a GPU (Raspberry Pi, laptops, industrial PCs). Inference runs on EVREN cloud GPUs — the UX feels local.

graph LR
    CAM["📷 Camera\nWebcam / RTSP / Video"] -->|frame| EC["EvrenCamera\ncompress + send"]
    EC -->|HTTPS| GPU["🖥️ EVREN GPU\nCluster"]
    GPU -->|JSON| EC
    EC -->|render| CAM

pip install evren-sdk[edge]

from evren_sdk import EvrenCamera

cam = EvrenCamera("evren_...", "owner/model", confidence=0.3)

cam.run(0)                                      # webcam, ESC to quit
cam.record("input.mp4", "output.mp4")           # process + save
for frame, result in cam.stream(0):             # custom loop
    print(f"{result.count} detections")
for path, result in cam.scan("images/"):        # folder scan
    print(f"{path.name}: {result.count} objects")

→ examples/05_edge_camera.py

Error Handling

from evren_sdk import (
    EvrenClient, InsufficientCreditsError,
    NotFoundError, RateLimitError, InferenceError,
)

try:
    result = client.predict("owner/model", "test.jpg")
except InsufficientCreditsError as e:
    print(f"Not enough credits — need: {e.required}, have: {e.available}")
except NotFoundError:
    print("Model not found")
except RateLimitError as e:
    time.sleep(e.retry_after)
except InferenceError:
    print("GPU server temporarily unavailable")

Every inference call consumes credits. When balance is too low, the SDK raises InsufficientCreditsError with e.required and e.available fields.

API Reference

Examples

Requirements

• Python >= 3.10
• httpx >= 0.27
• opencv-python >= 4.8 (only for evren-sdk[edge])

License

Apache License 2.0