Okuma 13.8 dkKategoriler: AI

Endüstriyel otomasyon, robotik ve akıllı izleme sistemlerinde birçok görev, belirli bir durumu değerlendirerek uygun iş akışını seçmeyi gerektirir. Bir olayı sınıflandırmak, bir kaydı incelemeye almak veya bir isteği başka bir modele yönlendirmek bu görevlere örnektir. Yapılandırılmış karar modelleri, bu tür işlemler için yazılımın doğrudan kullanabileceği sonuçlar üretir.

Jev nedir, neden önemlidir?

Jev, TypeSafe AI’nin “System One” olarak adlandırdığı model yaklaşımının ilk örneğidir. Modele, değerlendirilecek durum ve bu duruma ilişkin sorular iletilir. Model, sorunun türüne göre bir seçenek, puan veya evet/hayır olasılığı döndürür. Bu yapı, TypeSafe dokümantasyonunda anlatıldığı biçimiyle, modelin verdiği kararların uygulama kodunda doğrudan kullanılmasını kolaylaştırır.

Örneğin bir bakım kaydı, “fiziksel hasar”, “kozmetik sorun” veya “bilgi yetersiz” seçeneklerinden biriyle sınıflandırılabilir. Uygulama, her seçenek için hesaplanan olasılığı kullanarak kaydı ilgili birime iletebilir ya da bir uzmanın incelemesine sunabilir. Böylece belirsizlik de iş akışında dikkate alınır. Modelin kararlarının doğruluğu ve ürettiği olasılıkların güvenilirliği ise hedef uygulamaya ait verilerle doğrulanmalıdır.

Jetson üzerinde yerel karar vermek

NVIDIA Jetson, uçta yapay zekâ ve robotik uygulamaları için geliştirilmiş bir platformdur; kurulum adımları Orin Nano kullanıcı kılavuzunda yer alır. Karar modelini cihaz üzerinde çalıştırmak, verilerin yerel olarak işlenmesini ve uzak servislere bağımlılığın azalmasını sağlayabilir. Uygun bir mimariyle, ağ bağlantısı olmadan da çıkarım yapılabilir.

Kullanım örnekleri

Aşağıdaki örnekler, bir karar modelinin iş akışına nasıl dahil edilebileceğini gösterir:

Kullanım alanı	Örnek girdi	Karar ve uygulamanın yapacağı işlem
Kalite kontrol	Görüntü işleme raporu: “Ürün gövdesinde çatlak tespit edildi.”	“Fiziksel hasar” olarak sınıflandırılan ürün, kontrol kuyruğuna alınabilir.
Bakım ve izleme	Servis kaydı: “Motor bölgesinden yeni bir ses geliyor; titreşim artışı gözlendi.”	Kayda, bakım incelemesindeki önceliğini belirlemek için bir puan verilebilir.
Model yönlendirme	“İki farklı arıza raporunu karşılaştır ve olası nedenleri açıkla.”	Çok adımlı analiz gerektiren istek, daha güçlü bir modele yönlendirilebilir.

Bu uygulamalarda karar modeli, sensörlerden veya diğer modellerden gelen durum özetini değerlendirir. Modelin ürettiği sonuca göre hangi işlemin yapılacağını ise uygulamanın kuralları belirler.

Yerel değerlendirme için d3-edge

vllm-sr/d3-edge, vLLM Semantic Router ekibinin Decision 3.0 ailesine ait yaklaşık 0,59 milyar parametreli bir karar modelidir; ağırlıkları Apache-2.0 lisansıyla Hugging Face’teki model kartında yayımlanmıştır. Metin, JSON, görüntü ve video girdilerini destekler. Jev’den ayrı bir modeldir; ancak benzer biçimde yapılandırılmış kararlar üretir.

Modelin küçük olması, kaynakları sınırlı cihazlarda denenmesini kolaylaştırır. Ancak toplam bellek gereksinimi ve performans, kullanılan çalıştırma ortamına, girdi boyutuna ve eşzamanlı istek sayısına da bağlıdır.

Jetson Orin Nano üzerinde değerlendirme akışı

Aşağıdaki değerlendirme süreci altı adımdan oluşur. Adımlar, imajın indirilmesinden model yanıtının işlenmesine kadar izlenecek sırayı gösterir. Komutlar, Jetson Orin Nano Developer Kit üzerinde yapılan ön değerlendirmede kullanılmıştır.

#	Adım	Beklenen sonuç
1	Konteyner imajını indirme	İmaj yerel Docker deposunda hazır olur.
2	Model ağırlıklarını indirme	Dosyalar `~/.cache/huggingface` altında bulunur.
3	Sunucuyu başlatma	API, `localhost:8000` üzerinde dinlemeye başlar.
4	Hazırlığı doğrulama	Sunucu, kullanılabilir modellerin listesini döndürür.
5	Karar isteği gönderme	Her sorunun yanıtı, `answers` alanında yer alır.
6	Yanıtı işleme	Kayıt ilgili kuyruğa yönlendirilebilir.

Ön koşullar

Hugging Face CLI — model ağırlıklarını hf download komutuyla indirmek için gereklidir.
NVIDIA konteyner çalıştırma ortamı — konteynerin GPU’ya erişebilmesi için gereklidir.
JetPack/CUDA ile uyumlu imaj — çalıştırma ortamı, cihazdaki JetPack ve CUDA sürümleriyle uyumlu olmalıdır.
Yeterli disk alanı — hem konteyner imajı hem de model ağırlıkları için yeterli alan bulunmalıdır.

1. Konteyner imajını indirme

Copy to Clipboard

İpucu — tekrarlanabilirlik: nightly etiketi zamanla değişebilir. Aynı ortamı yeniden kurmanız gerekiyorsa kullandığınız imajın özet değerini (digest) kaydedin. İmaj etiketleri ve özet değerleri hakkında ayrıntı vLLM Docker dokümantasyonunda yer alır.

2. Model ağırlıklarını indirme

Copy to Clipboard

Not: Ağırlıklar, Hugging Face önbelleğine (~/.cache/huggingface) indirilir. Bir sonraki adımda bu dizin konteynere bağlandığı için ağırlıkların her çalıştırmada yeniden indirilmesi gerekmez.

3. Sunucuyu başlatma

Copy to Clipboard

Komuttaki parametreler:

Parametre	Görevi
`--gpus all`	Konteynerin tüm GPU’lara erişmesini sağlar.
`--ipc=host`	vLLM’in işlemler arası veri paylaşımı için ana sistemin IPC alanını kullanmasını sağlar.
`-p 8000:8000`	Konteynerdeki sunucunun 8000 numaralı portuna ana sistemin aynı portundan erişilmesini sağlar.
`-v ~/.cache/huggingface:...`	İndirilen ağırlıkların konteyner içinden okunmasını sağlar.
`-v vllm-cache:...`	vLLM önbelleğini adlandırılmış bir Docker biriminde (volume) kalıcı olarak saklar.
`vllm-sr/d3-edge`	İmaj adından sonra gelen bu argüman, sunucunun yükleyeceği modeli belirtir.

Not: Konteyner çalışırken modelin yüklenmesine ilişkin günlükler terminalde görüntülenir. --rm parametresi nedeniyle konteyner durdurulduğunda silinir; imaj, model ağırlıkları ve vllm-cache adlı Docker birimi ise diskte kalır.

4. Sunucunun hazır olduğunu doğrulama

Karar isteği göndermeden önce, ayrı bir terminalden sunucunun yanıt verip vermediği kontrol edilebilir:

Copy to Clipboard

Kontrol: Sunucu, yanıt olarak kullanılabilir modellerin listesini döndürür. Bu istek başarıyla tamamlandığında karar uç noktası da istek almaya hazırdır.

5. Karar isteği gönderme

Karar istekleri /v1/systemone uç noktasına gönderilir. İsteğin gövdesi üç ana alandan oluşur: kullanılacak model, değerlendirilecek durum ve sorular.

Alan	Görevi
`model`	Sunucu başlatılırken belirtilen modelin adı; `docker run` komutundaki model argümanıyla aynı olmalıdır.
`state`	Değerlendirilecek durum: metin ya da JSON.
`questions`	Her soru kimliğini ilgili soru tanımıyla eşleştiren yapı; tek istekte birden fazla soru tanımlanabilir.
`questions..type`	Sorunun türü. `choice` seçeneklerden birini seçer; `noul` evet olasılığını, `score` ise sıralı düzeylere dayanan bir puanı döndürür.
`questions..instructions`	Modelden ne istendiğini anlatan tek cümle.
`questions..criteria`	Soru türüne göre seçenekleri, düzeyleri veya evet/hayır açıklamalarını içerir. Yanıt, bu tanıma göre oluşturulur.

Üç soru türü desteklenir:

`type`	`criteria`	Dönen alan
`choice`	Seçenek adı → açıklama (veya `null`)	`choice`, `probabilities`, `confidence`
`noul`	`null` ya da isteğe bağlı `true` / `false` açıklamaları	`noul` (evet olasılığı), `probabilities`, `confidence`
`score`	Sıralı düzey adlarının listesi	`score` (Sıfırdan başlayan indekslere göre hesaplanan beklenen düzey), `legend`, `probabilities`, `confidence`

noul, evet/hayır sorusunun API’deki tip adıdır; dönen noul alanı evet olasılığını verir. Kategori seçimi için choice, evet/hayır kararı için noul, sıralı bir derecelendirme için score kullanılır. Bir istekte birden fazla soru gönderilebilir; her soru ayrı ayrı değerlendirilir ve yanıtı, answers alanında soru kimliğiyle yer alır. choice için en az bir seçenek, score için en az iki düzey tanımlanmalıdır. d3-edge’de bir choice sorusu en fazla 255 seçenek içerebilir.

Not — etiketler: d3-edge, seçenekleri birer kod: metin satırı olarak okur; choice seçenekleri ve score düzeyleri birden fazla kelimeden oluşabilir. choice anahtarları yanıtta aynen döndüğü için uygulama kodunuzda tutarlı adlar kullanın. İstek reddedilirse curl çağrısındaki --fail-with-body parametresi, hata yanıtının gövdesini terminalde gösterir. Böylece hangi alanda sorun olduğu görülebilir. Alanların ayrıntılı tanımı vLLM Decision 3.0 dokümantasyonunda yer alır.

Örnek 1 — tek soru (choice)

Örneğin bir ürün inceleme raporunu sınıflandırmak için aşağıdaki istek kullanılabilir. state alanı raporun Türkçe özetini içerir. durum anahtarı altında tanımlanan soru ise modelden bu özeti üç seçenekten biriyle sınıflandırmasını ister.

Copy to Clipboard

Örnek 2 — tek istekte üç soru (choice + noul + score)

Aynı çağrıda farklı soru türleri kullanılabilir. Aşağıdaki istek, siparişle ilgili talebin hangi ekibe yönlendirileceğini, müşterinin elinde fiş bulunup bulunmadığını ve talebin aciliyetini değerlendirir:

Copy to Clipboard

state alanı, düz metin yerine bir JSON nesnesi de içerebilir. d3-edge, bu alandaki JSON verisini metin olarak işler. Aynı questions yapısı, state alanı JSON olduğunda da kullanılabilir.

6. Yanıtı işleme

Sunucu yanıtında her soru için ayrı bir blok yer alır. Uygulamanın kullanacağı alanlar, soru türüne göre değişir:

Alan	Soru türü	Anlamı
`answers..choice`	`choice`	Modelin seçtiği seçenek (ör. `fiziksel_hasar`).
`answers..noul`	`noul`	Evet olasılığı (0–1).
`answers..score`	`score`	Sıfırdan başlayan indekslere göre hesaplanan beklenen düzey; örneğin `1.4`, iki düzey arasındaki bir eğilimi gösterir.
`answers..legend`	`score`	Düzey indekslerini düzey adlarıyla eşleştirir.
`answers..probabilities`	tümü	Seçeneklere, düzeylere veya evet/hayır yanıtlarına ait olasılıklar; karar eşiğiyle karşılaştırılır.
`answers..confidence`	tümü	Seçilen etiketin, tüm sözlük üzerinden hesaplanan olasılığıdır; kalibre edilmiş bir güven değeri değildir.

Not — tekrarlanabilirlik: Aynı istek tekrarlandığında olasılıklar tam olarak aynı çıkmayabilir. Değerler, aynı grupta işlenen isteklere ve önek önbelleğine bağlı olarak değişebilir. Sonuçların birebir tekrarlanması gereken ölçümlerde VLLM_BATCH_INVARIANT=1 ayarı kullanılabilir.

Uygulama bu alanları kullanarak kaydı ilgili kuyruğa yönlendirebilir. Karar eşiği, doğrulama verileri kullanılarak belirlenmelidir.

Python SDK ile asenkron kullanım

Aynı karar akışı, Python uygulamasına da taşınabilir. TypeSafe Python SDK’nin asenkron kullanım örneğinde sorular Choice, Noul ve Score sınıflarıyla tanımlanır; istek, await client.system_one(...) çağrısıyla gönderilir. Bu yaklaşım, uygulamanın sunucu yanıtını beklerken diğer asenkron görevleri sürdürebilmesini sağlar.

Önce SDK’yi kurun:

Copy to Clipboard

Aşağıdaki örnek, önceki sipariş senaryosunu yerel d3-edge sunucusuna göndermek üzere hazırlanmıştır. Bağlantı adresi ve model adı, SDK’nin istemci ayarları kullanılarak belirtilir. compression=False, isteğin sıkıştırılmadan gönderilmesini sağlar.

Deneme durumu: Bu örnek, sunucu kapalı olduğu için canlı ortamda çalıştırılmamıştır. SDK’nin farklı bir sunucuyla kullanılabilmesi için o sunucunun TypeSafe API biçimiyle uyumlu olması gerekir. Yerel vLLM sürümünüzün istek ve yanıt biçimiyle uyumluluğu ayrıca doğrulanmalıdır. SDK bir API anahtarı istediği için aşağıda local değeri kullanılmıştır; bu değer, kimlik doğrulama etkin olmayan yerel sunucu içindir. Sunucunuzda kimlik doğrulama etkinse geçerli anahtarı kullanın.

Kodu karar_async.py adıyla kaydedin:

Copy to Clipboard

import asyncio
import json

from typesafe_sdk import AsyncTypeSafeClient, Choice, Noul, Score

async def main() -> None:
    async with AsyncTypeSafeClient(
        base_url="http://localhost:8000",
        api_key="local",
        model="vllm-sr/d3-edge",
        compression=False,
    ) as client:
        response = await client.system_one(
            state=(
                "Sipariş dün hasarlı geldi. Müşterinin elinde fiş var "
                "ve bugün değişim istiyor."
            ),
            questions={
                "yonlendirme": Choice(
                    instructions="Bu isteği hangi ekip ele almalı?",
                    criteria={
                        "iade": "İadeler, değişimler ve hasarlı teslimatlar",
                        "faturalama": "Ödemeler, faturalar ve ücretler",
                        "teknik": "Ürün kurulumu ve arızalar",
                    },
                ),
                "fis": Noul(instructions="Müşterinin elinde fiş var mı?"),
                "aciliyet": Score(
                    instructions="Bu istek ne kadar acil?",
                    criteria=["Rutin", "Kısa sürede", "Bugün"],
                ),
            },
        )

ozet = {
        "ekip": response.choices["yonlendirme"].choice,
        "fis_var_olasiligi": round(response.nouls["fis"].noul, 3),
        "aciliyet_puani": round(response.scores["aciliyet"].score, 2),
    }
    print(json.dumps(ozet, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    asyncio.run(main())

Sunucu hazır olduğunda örneği çalıştırın:

Copy to Clipboard

Örnek çıktı nasıl görünür?

Temsili çıktı: Aşağıdaki değerler, anlatımı somutlaştırmak için hazırlanmıştır; çalışan bir modelden alınmamıştır. Bir performans ölçümü veya doğruluk sonucu değildir.

Copy to Clipboard

Bu çıktı, sunucunun ham JSON yanıtı değil, Python kodunun yanıttan seçerek oluşturduğu özettir. ekip, talebin iade ve değişimle ilgilenen ekibe yönlendirildiğini gösterir. fis_var_olasiligi, müşterinin elinde fiş bulunduğuna ilişkin evet olasılığıdır. Bu değer, tek başına modelin yüzde 98 doğrulukla çalıştığı anlamına gelmez.

Aciliyet düzeyleri sırasıyla 0 = Rutin, 1 = Kısa sürede, 2 = Bugün olarak tanımlanmıştır. Temsili 1.85 puanı, değerlendirmenin “Bugün” düzeyine yakın olduğunu gösterir. Uygulama, bu sonuçları kendi yönlendirme kurallarıyla birlikte kullanabilir; otomatik işlem eşikleri, gerçek verilerle doğrulandıktan sonra belirlenmelidir.

TypeSafe’in barındırdığı API ile kullanım

Jev’i TypeSafe’in hizmeti üzerinden denemek için istemciyi aşağıdaki gibi oluşturabilirsiniz. Diğer soru tanımları ve yanıtı okuyan kod aynı kalabilir:

Copy to Clipboard

Bu kullanımda TYPESAFE_API_KEY ortam değişkenine geçerli TypeSafe API anahtarınızı tanımlamanız gerekir. base_url verilmediğinde SDK, TypeSafe’in API’sine bağlanır; dolayısıyla istekler Jetson üzerindeki yerel modele gönderilmez. Model seçimi ve bağlantı ayarları SDK kullanım kılavuzunda açıklanmıştır.

Bu değerlendirme süreci, Jetson üzerinde ölçülmüş performans sonuçları içermemektedir. Sistem gerçek kullanım ortamına alınmadan önce donanım uyumluluğu, Türkçe ve uygulama alanına özgü verilerde karar kalitesi, yanıt gecikmesi ve bellek tüketimi birlikte değerlendirilmelidir.