Geleneksel yazılım mimarilerinde bir uygulamanın davranışını tahmin etmek nispeten kolaydır. Girdiler bellidir, mantıksal deterministik kurallar (if/else blokları) tanımlıdır ve hata durumunda stack trace bize hatanın tam olarak hangi satırda patladığını söyler. Ancak işin içine büyük dil modelleri (LLM) ve özellikle kendi kararlarını alabilen yapay zeka ajanları (AI Agents) girdiğinde, deterministik dünya tamamen yıkılır.
Production ortamına (canlıya) alınan bir AI ajanı, kullanıcıdan gelen tek bir girdi karşısında arka planda onlarca farklı adım atabilir. Bir veri tabanına sorgu atabilir, harici bir API’ye bağlanabilir, aldığı cevaba göre prompt’unu dinamik olarak değiştirip modele tekrar gidebilir. Bu kontrolsüz döngü sırasında ajanın nerede takıldığını, neden saçmaladığını (hallucination), hangi aşamada ne kadar token harcayarak bütçenizi erittiğini sadece geleneksel loglama araçlarıyla (örneğin Python'daki logging modülü veya print ifadeleriyle) anlamanız imkansızdır.
Canlı ortamdaki ajanların bu öngörülemez doğasını kontrol altına almak, hataları debug etmek ve maliyetleri optimize etmek için LLM Observability (Gözlemlenebilirlik) ve Tracing (İzleme) kavramları devreye girer. Bu teknik rehberde, günümüzün en güçlü iki gözlemlenebilirlik aracı olan LangSmith ve açık kaynaklı Arize Phoenix kullanarak AI ajanlarınızı canlıda nasıl izleyeceğinizi, hata ayıklayacağınızı ve optimize edeceğinizi en ince detayına kadar inceleyeceğiz.
1. Geleneksel Loglama Neden Yetersiz? LLM Tracing Nedir?
Geleneksel bir API hata verdiğinde log dosyasında HTTP 500 hatasını ve hatanın kaynağı olan veri tabanı bağlantı problemini görebilirsiniz. Bir AI ajanında ise sistem hata vermeyebilir; kullanıcıya gayet düzgün bir cümleyle yanlış bir cevap dönebilir. Veya bir CrewAI ya da LangGraph ajanı, belirlediğiniz bir aracı (tool) doğru parametrelerle çağıramadı için kendi kendine sonsuz bir düşünce döngüsüne (Thought -> Action -> Observation) girebilir.
Console çıktısına bakarak şu soruların cevabını bulamazsınız:
- Model, sistem prompt'undaki hangi kuralı çiğnedi?
- Vektör veri tabanından (Vector DB) dönen veri (RAG context) yeterince kaliteli miydi yoksa modele alakasız dökümanlar mı beslendi?
- Hangi adımda gecikme (latency) tavan yaptı?
- İç içe geçmiş zincirlerde (nested chains) hangi alt fonksiyon modeli yanlış yönlendirdi?
LLM Tracing, bir ajanın tetiklendiği ilk andan kullanıcıya yanıt döndüğü son ana kadar gerçekleşen tüm alt süreçlerin (grafik ağacının) kronolojik ve hiyerarşik olarak haritalandırılmasıdır. Ajanın yaptığı her model çağrısı (LLM call), çalıştırdığı her araç (tool execution) ve gerçekleştirdiği her veri tabanı sorgusu birer span (alt süreç) olarak kaydedilir. Bu span'lerin birleşimi ise bize tüm hikayeyi anlatan bir trace (iz) sunar.
2. LangSmith ile Bulut Tabanlı Canlı İzleme Mimarisi
LangChain ekibi tarafından geliştirilen LangSmith, özellikle üretim ortamındaki LLM uygulamalarını izlemek için endüstri standardı haline gelmiş ticari (ancak geliştiriciler için ücretsiz katmanı olan) bir SaaS platformudur. LangChain kütüphaneleriyle yerel olarak (native) entegre çalışır ancak sadece LangChain ile sınırlı değildir; doğrudan OpenAI, Anthropic veya CrewAI projelerinde de kullanılabilir.
Entegrasyon ve Ortam Değişkenlerinin Ayarlanması
LangSmith'in en büyük avantajı, kodunuzun mimarisini değiştirmeden, sadece birkaç ortam değişkeni (environment variables) ekleyerek tüm sistemi otomatik olarak izleyebilmenizdir.
İlk olarak sisteminize gerekli kütüphaneleri kurun:
pip install langchain langchain-openai langsmithArdından, projenizin kök dizininde bulunan .env dosyanıza veya işletim sisteminizin ortam değişkenlerine aşağıdaki kayıtları ekleyin:
# LangSmith İzlemeyi Aktif Eder
export LANGCHAIN_TRACING_V2="true"
# LangSmith API Anahtarınız
export LANGCHAIN_API_KEY="ls__your_secret_api_key_here"
# Logların hangi proje altında toplanacağını belirler
export LANGCHAIN_PROJECT="my-production-agent-v1"
# İsteğe bağlı: Kullanılan LLM sağlayıcısının anahtarı
export OPENAI_API_KEY="sk-proj-..."Python Kod Seviyesinde Takip
Yukarıdaki ortam değişkenleri ayarlandığında, arka planda çalışan LangChain motoru veya HTTP istemcileri atılan her adımı otomatik olarak LangSmith sunucularına asenkron olarak postalar. Kodunuzda ekstra bir log_yaz() fonksiyonu çağırmanıza gerek kalmaz.
Aşağıdaki örnekte, iki farklı araca (hava durumu sorgulama ve matematik hesaplama) sahip gelişmiş bir OpenAI fonksiyon çağrısı (function calling) ajanı kurgulayalım:
import os
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.tools import tool
# 1. Ajanın Kullanacağı Araçları (Tools) Tanımlıyoruz
@tool
def get_user_balance(user_id: str) -> float:
"""Verilen kullanıcı kimliğine ait cüzdan bakiyesini döner."""
# Production simülasyonu: Gerçek bir DB sorgusu gibi düşünün
if user_id == "usr_99":
return 1450.75
return 0.0
@tool
def calculate_discount(price: float, ratio: float) -> float:
"""Bir fiyat üzerine uygulanacak indirim tutarını hesaplar."""
return price * (ratio / 100)
tools = [get_user_balance, calculate_discount]
# 2. Prompt Şablonunu Oluşturuyoruz
prompt = ChatPromptTemplate.from_messages([
("system", "Sen bakiye ve indirim işlemlerini yöneten profesyonel bir finans asistanısın. Sana verilen araçları mantıklı sırayla kullan."),
MessagesPlaceholder(variable_name="chat_history"),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
])
# 3. LLM ve Ajan Yapılandırması
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 4. Ajanı Çalıştırıyoruz
if __name__ == "__main__":
# Bu sorgu hem get_user_balance hem de calculate_discount aracını tetikleyecek zincirleme bir işlem başlatır.
response = agent_executor.invoke({
"input": "usr_99 id'li kullanıcının bakiyesini sorgula ve bu bakiye üzerinden %15 indirim yaparsak yeni bakiye ne olur hesapla.",
"chat_history": []
})
print("Ajan Cevabı:", response["output"])LangSmith Arayüzünde Hata Ayıklama (Debugging)
Yukarıdaki script çalıştırıldığında LangSmith paneline girdiğinizde projenizin altında yeni bir trace satırı görürsünüz. Bu satıra tıkladığınızda karşınıza ağaç yapısında bir arayüz çıkar:
- Üst Düğüm (AgentExecutor): Toplam geçen süreyi (milisaniye cinsinden) ve harcanan toplam token miktarını gösterir.
- İlk Alt Düğüm (ChatOpenAI): Kullanıcı girdisi ile sistem prompt'unun nasıl birleştiğini net olarak görürsünüz. Modelin ilk cevabında
get_user_balance(user_id='usr_99')fonksiyonunu çağırmaya karar verdiğini (tool_calls) ham JSON formatında incelersiniz. - Üçüncü Düğüm (get_user_balance): Aracın içine giren parametreyi ve dışarı çıkan
1450.75değerini doğrularsınız. - Dördüncü Düğüm (ChatOpenAI - Adım 2): Modelin ilk fonksiyonun sonucunu alıp, ikinci fonksiyon olan
calculate_discount(price=1450.75, ratio=15)adımını nasıl planladığını görürsünüz.
Eğer ajanın hata yapmasını istiyorsanız, girdiyi "Bilinmeyen bir kullanıcının bakiyesini bul" şeklinde değiştirin. LangSmith arayüzünde fonksiyonun 0.0 döndüğünü, modelin bu durumu nasıl yorumladığını ve nerede mantık hatasına düştüğünü saniyeler içinde tespit edebilirsiniz.
3. Arize Phoenix ile Açık Kaynaklı (Open-Source) ve Lokal İzleme
Veri gizliliği (data privacy) ve KVKK/GDPR regülasyonları nedeniyle, canlı ortamdaki kullanıcı konuşmalarını veya şirket içi hassas verileri LangSmith gibi harici bir bulut SaaS sağlayıcısına göndermek her senaryoda mümkün olmayabilir. İşte bu noktada tamamen açık kaynak kodlu, veriyi kendi sunucunuzda tutmanıza izin veren ve OpenInference (OpenTelemetry tabanlı) standartlarını kullanan Arize Phoenix devreye girer.
Phoenix, Docker üzerinde veya doğrudan bir Python sürecinin içinde yerel bir HTTP sunucusu olarak ayağa kalkabilir. LlamaIndex, LangChain, DSPy ve ham OpenAI SDK yapılarını tek bir satır komutla enjekte (instrumentation) edebilir.
Phoenix Kurulumu ve Başlatılması
Projenize Phoenix ve gerekli telemetri araçlarını dahil edin:
pip install arize-phoenix openinference-instrumentation-langchain opentelemetry-sdk opentelemetry-exporter-otlpPhoenix sunucusunu lokalinizde veya sunucunuzda başlatmak için terminalden şu komutu çalıştırmanız yeterlidir:
phoenix startBu komutun ardından tarayıcınızda http://localhost:6006 adresinde yerel izleme arayüzü aktif olacaktır.
Kod Entegrasyonu (Instrumentor Mantığı)
Phoenix, sistem genelindeki LLM çağrılarını yakalamak için OpenTelemetry standartlarını kullanır. Aşağıdaki örnekte, Phoenix’in kodunuza nasıl enjekte edileceğini görebilirsiniz:
import phoenix as px
from openinference.instrumentation.langchain import LangChainInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
# 1. Phoenix İzleyicisini Başlatın veya Mevcut Yerel Sunucuya Bağlayın
px.launch_app()
# 2. OpenTelemetry Sağlayıcısını Yapılandırın ve Logları Phoenix'e Yönlendirin
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
SimpleSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:6006/v1/traces"))
)
trace.set_tracer_provider(tracer_provider)
# 3. LangChain İçin Otomatik Entegrasyonu Aktif Edin
LangChainInstrumentor().instrument()
# --- Bu satırdan sonra yazacağınız tüm LangChain kodları otomatik olarak Phoenix'e düşecektir ---
from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
llm = ChatOpenAI(model="gpt-4o")
prompt = PromptTemplate.from_template("Bana {konu} hakkında teknik ve kısa bir bilgi ver.")
chain = prompt | llm
if __name__ == "__main__":
# Test çalıştırması
print(chain.invoke({"konu": "Kuantum Bilgisayarlarında Hata Düzeltme (Error Correction)"}))Phoenix ile Otomatik LLM Değerlendirmesi (Evaluation)
Phoenix’i rakiplerinden ayıran en kritik özelliklerden biri, sadece log toplamakla kalmayıp, topladığı loglar üzerinde Evals (Otomatik Değerlendirme) çalıştırabilmesidir. Canlı ortamdan geçen binlerce konuşmayı tek tek okumanız imkansızdır. Phoenix; verileriniz içerisinden rastgele veya belirli kurallara göre örneklemler seçerek başka bir "Hakem LLM" (özel yapılandırılmış bir GPT-4o gibi) yardımıyla şu analizleri yapabilir:
- Hallucination Rate (Halüsinasyon Oranı): Üretilen cevap, vektör veri tabanından gelen RAG dökümanlarıyla ne kadar uyuşuyor? (Faithfulness ölçümü).
- QA Correctness (Soru-Cevap Doğruluğu): Ajanın verdiği cevap, kullanıcı beklentisini teknik olarak karşılıyor mu?
- Toxicity (Zararlı İçerik): Model canlıda manipüle edilerek küfürlü, taraflı veya zararlı içerik üretmeye zorlanmış mı?
Phoenix paneli üzerinden "Evaluations" sekmesine gelerek bu testleri otomatik olarak tetikleyebilir ve canlıdaki uygulamanızın doğruluk skorunun zamana bağlı grafiğini çıkartabilirsiniz.
4. Production Ortamı İçin En İyi Pratikler (Best Practices)
Bir AI ajan sistemini lokalde test etmekle binlerce aktif kullanıcının olduğu canlı ortama almak arasında ciddi mimari farklar vardır. Canlıya çıkmadan önce aşağıdaki 3 ana başlığı mutlaka yapılandırmalısınız:
1. Token ve Maliyet Sınırları Koyma (Rate Limiting & Cost Guard)
Ajan tasarımlarında en büyük risk, ajanın mantıksal bir hatadan ötürü kendi kendini tetikleyen bir döngüye girmesidir. Örneğin, ajan bir aracı çağırır; araç hata döner; ajan hatayı çözmek için tekrar aracı çağırır. Bu süreç siz fark edene kadar dakikalarca sürebilir ve binlerce dolarlık OpenAI faturasına yol açabilir.
AgentExecutorveyaLangGraphkullanırken mutlakamax_iterations(maksimum adım sayısı) parametresi tanımlayın. Bir istek için ajanın en fazla 5 veya 10 adım atmasına izin verin.- LangSmith paneli üzerinden günlük veya proje bazlı maliyet uyarıları (cost alerts) kurun. Belirlenen bütçe aşıldığında API isteklerini kesecek webhook yapılandırmalarından yararlanın.
2. Kullanıcı Gizliliği ve PII Maskeleme
Canlı ortamda kullanıcılar ajana kredi kartı numaraları, şifreler veya kişisel sağlık verileri (PII) girebilir. Bu verilerin ham hallerinin LangSmith bulutuna veya Phoenix log veri tabanına açık metin (cleartext) olarak kaydedilmesi güvenlik ihlalidir.
- Loglama katmanına girmeden önce prompt girdilerini
Microsoft Presidiogibi açık kaynaklı PII kütüphaneleriyle tarayın. - E-posta, telefon ve isim gibi kritik alanleri regex veya hafif NLP modelleriyle maskeleyerek (
[KİŞİSEL VERİ MASKELENDİ]) telemetri sistemine o şekilde besleyin.
3. Asenkron Loglama ve Performans (Latency) Optimizasyonu
Telemetri ve tracing araçları, ağ üzerinden HTTP istekleri atarak logları sunucuya gönderir. Eğer bu işlem senkron (synchronous) olarak yapılırsa, kullanıcınız ajanın cevabını beklerken bir de log sunucusunun ağ gecikmesini beklemek zorunda kalır.
- LangSmith zaten doğası gereği logları arka planda çalışan asenkron bir iş parçacığı (worker thread) ile gönderir.
- Phoenix entegrasyonunda ise OpenTelemetry yapılandırmasını yaparken
SimpleSpanProcessoryerine mutlaka production ortamları için tasarlanmış olanBatchSpanProcessoryapısını kullanın. Bu yapı, logları bellekte toplar ve uygulamanın ana akışını bloke etmeden belirli aralıklarla toplu (batch) olarak gönderir.
# Production için doğru Phoenix / OpenTelemetry işlemcisi
from opentelemetry.sdk.trace.export import BatchSpanProcessor
tracer_provider.add_span_processor(
BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:6006/v1/traces"))
)Sonuç
Yapay zeka ajanlarını kara kutu (black box) olmaktan çıkarıp şeffaf, ölçülebilir ve izlenebilir sistemler haline getirmek, production kalitesinde bir SaaS yazılımı sunmanın ilk şartıdır.
Hızlı prototipleme, takımlar arası iş birliği ve detaylı görsel analizler için bulut tabanlı LangSmith biçilmiş kaftandır. Veri egemenliği, lokal altyapı zorunlulukları ve otomatik değerlendirme (evaluation) süreçleri için ise açık kaynaklı Arize Phoenix en güçlü alternatifinizdir. Projenizin ihtiyaçlarına göre bu iki araçtan birini sisteminize dahil etmek, sizi canlı ortamda yaşanacak kabuslardan koruyacaktır.
