OpenTelemetry ile Sağlayıcıdan Tarafsız LLM Gözlemlenebilirliği Nasıl Oluşturulur

LLM gözlemlenebilirliği, her uygulama ekibi sağlayıcı yanıtlarını kendi biçiminde günlüğe kaydettiğinde bozulur. Bir olay sırasında platform ekiplerinin somut soruları yanıtlaması gerekir: isteği hangi ekip yaptı, hangi API anahtar kapsamı kullanıldı, hangi model talep edildi, hangi sağlayıcı bunu gerçekten sundu, yeniden deneme mi yoksa geri dönüş mü gerçekleşti, kaç jeton tüketildi, hangi gecikme kümesi değişti ve başarısızlığa hangi hata sınıfı neden oldu. Ayrıca ham istemleri, tamamlamaları, sağlayıcı anahtarlarını veya müşteri tanımlayıcılarını genel günlük depolarına kopyalamadan bu yanıtlara ihtiyaçları vardır.

Pratik yanıt, çok modelli API ağ geçidini gözlemlenebilirlik kontrol noktası olarak kullanmaktır. Uygulama düzeyinde izleme hala önemlidir, ancak ağ geçidi, sağlayıcı seçiminin, yeniden denemelerin, geri dönüşlerin, kullanım muhasebesinin, istek sahipliğinin ve gizlilik uygulamasının telemetrinin aşağı yönlü araçlara ulaşmadan önce normalleştirilebildiği yerdir. Kurumsal Yüksek Lisans API işleten ekipler için bu, dağınık hata ayıklama verileri ile sağlayıcıdan bağımsız işletim modeli arasındaki fark haline gelir.

Önce Gözlemlenebilirlik Sözleşmesini Tanımlayın

Kontrol paneli ekran görüntüleri ile değil, yazılı bir özellik sözleşmesiyle başlayın. Sözleşme, her LLM isteğinin yayması gereken minimum meta verileri, hangi alanların ağ geçidinden çıkmasına izin verildiğini, hangi alanların kısıtlandığını ve hangi alanların hiçbir zaman dışa aktarılmadığını tanımlamalıdır.

Yararlı bir temel sözleşme, sahiplik, yönlendirme, model, kullanım, gecikme ve sonuç meta verilerini içerir. Sahiplik özellikleri; kuruluşu, ekibi, ortamı, iş yükünü, uygulamayı ve API anahtar kapsamını tanımlar. Yönlendirme öznitelikleri, ağ geçidi rotasını, politika sürümünü, istenen sağlayıcıyı, istenen modeli, seçilen sağlayıcıyı, seçilen modeli, yeniden deneme sayısını, geri dönüş sayısını ve akışın kullanılıp kullanılmadığını tanımlar. Kullanım özellikleri; giriş belirteçlerini, çıktı belirteçlerini, önbelleğe alınmış giriş belirteçlerini, mevcut olduğunda akıl yürütme belirteçlerini, istek sayısını ve tahmini maliyet sınıfını yakalar. Sonuç özellikleri durumu, güvenli olduğunda sağlayıcı hata kodunu, normalleştirilmiş hata sınıfını, doğrulama sonucunu, zaman aşımı durumunu ve son yanıt modelini yakalar.

Sözleşme sağlayıcısını tarafsız tutun. Hız sınırı yanıtı, aşırı yüklenmiş model yanıtı, şema doğrulama hatası, güvenlik reddi, zaman aşımı veya bağlam penceresi hatası gibi sağlayıcıya özgü bir hata, kontrol panellerinin sağlayıcılar arasında gruplandırabileceği normalleştirilmiş bir hata sınıfıyla eşlenmelidir. Orijinal sağlayıcı hata kodu faydalı olabilir ancak birincil kontrol paneli boyutu olarak değil, kısıtlı teşhis verileri olarak ele alınmalıdır.

Ağ Geçidi Merkezli Yayılma Modeli Kullanın

Net bir izleme yapısı, LLM telemetrisinin düz bir aralık yığınına dönüşmesini önler. Ağ geçidinin gerçekleştirdiği iş için bir gelen uygulama istek aralığı, bir mantıksal LLM işlem aralığı ve alt aralıklar kullanın.

Tipik bir hiyerarşi şuna benzer:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

Gelen istek aralığı, arayanın ağ geçidine olan isteğini temsil eder. Mantıksal LLM işlem aralığı, ağ geçidi birden fazla sağlayıcı girişiminde bulunsa bile kullanıcının görebildiği LLM görevini temsil eder. Sağlayıcı girişim aralıkları, API numaralı bir yukarı akış modeline yapılan her gerçek çağrıyı yakalar. Alma, araç ve doğrulama aralıkları, nihai yanıtın üretilmesinin bir parçası olduklarında mantıksal işlemin alt öğeleri olmalıdır.

Bu ayırma, olaylar sırasında önemlidir. Bir istek bir modelden diğerine düşerse, ilk sağlayıcı girişimi başarısız olurken mantıksal işlem başarılı olabilir. Nihai çıktı şema doğrulamasında başarısız olursa, mantıksal işlem başarısız olurken sağlayıcı girişimi teknik olarak başarılı olabilir. Ayrı aralıklar olmadan, kontrol panelleri sağlayıcı hatalarını başarılı son kullanıcı yanıtlarının arkasına gizler veya başarılı bir şekilde kurtarılan hataları abartır.

Dahili Bir Eşleyicinin Arkasındaki OpenTelemetry GenAI Özniteliklerini Haritalayın

OpenTelemetry anlam kuralları mevcuttur; böylece telemetri üreticileri kod tabanları, kitaplıklar ve platformlar genelinde ortak adlar ve nitelikler kullanır.OpenTelemetry projesi artık Üretken Yapay Zeka kurallarını ayrı bir GenAI deposuna yönlendiriyor ve bu kurallar, sağlayıcı adı, istenen model, yanıt modeli, giriş jetonları, çıktı jetonları, akıl yürütme jetonları ve önbelleğe alınmış giriş jetonları gibi model istek ve yanıt niteliklerini tanımlıyor.

Bu GenAI niteliklerini uygun oldukları yerde kullanın, ancak ham özellik adlarını ağ geçidi koduna dağıtmayın. Bunları küçük bir telemetri eşleyicisinin arkasına sarın. Bu eşleyicinin dahili bir istek kaydını kabul etmesi ve standartlaştırılmış yayılma nitelikleri üretmesi gerekir.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

Eşleştirici, standart alanlar için OpenTelemetry GenAI niteliklerini ve iş bağlamı için özel ağ geçidi niteliklerini yayınlayabilir. Özel nitelikleri kontrollü bir ad alanı altında tutun; örneğin llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy ve llm_gateway.workload_class

Bu tasarım, kod tabanını kayıptan korurken size tedarikçiden bağımsız telemetri sağlar. GenAI kuralları hâlâ gelişmekte olduğundan eşleyici, adların her işleyiciyi, yeniden deneme modülünü, akış bağdaştırıcısını ve doğrulama bileşenini düzenlemeden değiştirilebildiği yerdir.

Meta Verileri Hassas İçerikten Ayırın

LLM izleri alışılmadık derecede hassastır çünkü en yararlı hata ayıklama verileri, geniş çapta saklanmaması gereken verilerle aynı olabilir: istemler, alınan belgeler, araç parametreleri, tamamlamalar, kullanıcı tanımlayıcıları, müşteri tanımlayıcılar ve ham sağlayıcı kimlik bilgileri. Varsayılan duruş meta veri öncelikli gözlemlenebilirlik olmalıdır.

Önerilen varsayılan alanlar arasında bilgi istemi karması, bilgi istemi şablonu kimliği, bilgi istemi sürümü, şema kimliği, araç adı, alma koleksiyonu, rota adı, belirteç sayıları, gecikme, normalleştirilmiş hata sınıfı ve doğrulama durumu yer alır. Bu alanlar, ham içeriği dışa aktarmadan birçok operasyonel soruyu yanıtlar.

Ham bilgi istemi ve tamamlama yakalama, dışa aktarmadan önce etkinleştirilmeli, zaman sınırlı, erişim kontrollü ve düzenlenmelidir. Kolaylık özelliği olarak genel olarak etkinleştirmeyin. Bir üretim olayı için içerik yakalama gerektiğinde, dar bir istek kümesine bir hata ayıklama bayrağı ekleyin, bu izleri kısıtlı bir arka uca yönlendirin ve kısa bir saklama aralığı ayarlayın.

Tanımlayıcıların karma hale getirilmesi otomatik olarak anonimleştirme değildir. Giriş alanı küçükse veya tahmin edilebilirse karma değerleri tahmin edilerek tersine çevrilebilir. Hassas müşteri veya kullanıcı tanımlayıcıları için, sıkı anahtar kontrollerle silmeyi, yedek kimlikleri, gruplandırmayı, kesmeyi veya anahtarlı karma oluşturmayı düşünün. Genel bir gizlilik yanıtı olarak değil, risk anlaşıldığında öncelikle istikrarlı korelasyon için karmaları kullanın.

Toplayıcıda Gizliliği Zorunlu Hale Getirin

OpenTelemetry kılavuzu, hassas verilerin dışa aktarmadan önce işlenmesi gerektiğini söylüyor. Toplayıcı, nitelikler, filtreleme, redaksiyon ve dönüştürme gibi işlemcileri kullanarak telemetri niteliklerini kaldırabilir, karma hale getirebilir, filtreleyebilir, düzeltebilir veya dönüştürebilir. Bu, Toplayıcı'yı, ağ geçidi araçlarının ardından ikinci bir savunma hattı haline getirir.

Pratik bir Toplayıcı ardışık düzeni, düşük riskli nitelikler için bir izin verilenler listesi kullanmalı, ham istem ve yanıt alanlarını varsayılan olarak silmeli, engellenen kalıplarla eşleşen değerleri maskelemeli ve içerik yakalama açıkça etkinleştirildiğinde daha yüksek hassasiyete sahip izleri ayrı olarak yönlendirmelidir. OpenTelemetry Collector öznitelik işlemcisi, silme ve karma gibi eylemleri destekler. Redaksiyon işlemcisi, izin verilenler listesinde olmayan öznitelikleri silmek ve engellenen kalıplarla eşleşen değerleri maskelemek için tasarlanmıştır.

Örneğin, ağ geçidi varsayılan olarak ham içerik yayınlamayı önleyebilirken, Toplayıcı, bir hata veya kitaplık entegrasyonu nedeniyle ortaya çıktıklarında llm.prompt.raw, llm.completion.raw, provider.api_key, authorization ve cookie gibi öznitelikleri silmeye devam eder. Bunu, güvenli olmayan verileri gelişigüzel yayınlamak için bir neden olarak değil, kapsamlı bir savunma kontrolü olarak değerlendirin.

Araç Yeniden Denemeleri, Geri Dönüşler ve Doğrulama Ayrı Ayrı

Yeniden denemeler ve geri dönüşler, API metriklerin toplamında genellikle görünmez. Bu görünmezlik iki operasyonel soruna neden oluyor. Birincisi, başarılı bir yanıt birden fazla başarısız girişimi gizleyebileceği için gecikme süresi düşebilir.İkincisi, tek bir kullanıcı isteği birden fazla yukarı yönlü model çağrısı oluşturabileceğinden maliyet artabilir.

Her sağlayıcı deneme aralığı, deneme numarasını, yeniden deneme nedenini, seçilen sağlayıcıyı, seçilen modeli, zaman aşımı bütçesini, gecikmeyi, mümkün olduğunda jeton kullanımını ve sonucu içermelidir. Bir geri dönüş meydana gelirse, geri dönüş aralığı, orijinal rota politikasını, geri dönüş nedenini ve son yanıt için fiilen kullanılan modeli tanımlamalıdır.

Yapılandırılmış çıktı doğrulaması, kendi aralığı veya olayı olmalıdır. Şema kimliğini, şema sürümünü, doğrulama sonucunu, onarım girişimi sayısını ve son durumu yakalayın. Geçersiz çıktının tamamını varsayılan olarak saklamayın. Doğrulama hatası, sağlayıcı aktarım hatasından işlevsel olarak farklıdır ve kontrol panelleri bunları bir arada bulanıklaştırmamalıdır.

Sağlayıcılar Değil, Sorular Çevresinde Kontrol Panelleri Oluşturun

Sağlayıcıdan bağımsız gözlemlenebilirlik, işletimle ilgili soruları doğrudan yanıtlamalıdır. Yararlı kontrol panelleri modele, sağlayıcıya, ekibe, ortama ve iş yükü sınıfına göre p95 ve p99 gecikmesini içerir; takıma ve rotaya göre jeton kullanımı; normalleştirilmiş hata sınıfına göre başarısızlık oranı; amplifikasyonu rota politikasına göre yeniden deneyin; talep edilen modele göre geri dönüş sıklığı; bilgi istemi şablonuna göre bağlam penceresi hataları; şemaya göre yapılandırılmış çıktı doğrulama hataları; ve başarısız, pahalı veya yavaş istekler için örneklenmiş izleme örnekleri.

Faturalandırma ve toplam kullanım raporlamasını örneklenmiş izlemelerin dışında tutun. Kuyruk örneklemesi hata ayıklama için kullanışlıdır ancak toplamları bozabilir. Token toplamları, talep sayıları ve maliyet defterleri, örneklenmemiş sayaçlardan, talep defterlerinden veya fatura mutabakat sistemlerinden gelmelidir. İzler pahalı veya yavaş bir isteğin neden gerçekleştiğini açıklamalıdır; bunlar finansal gerçeğin tek kaynağı olmamalıdır.

Yüksek Değerli İzler için Kuyruk Örneklemeyi Kullanın

OpenTelemetry Collector kuyruk örnekleme işlemcisi, niteliklere ve sayısal değerlere dayalı politikalar da dahil olmak üzere, aralıklar tamamlandıktan sonra örnekleme kararları verebilir. Bu, LLM trafiği için faydalıdır çünkü genellikle bir izlemenin değerli olup olmadığını yalnızca yanıt tamamlandıktan sonra bilirsiniz.

Sağlayıcı hataları, doğrulama hataları, çok yüksek gecikme süresi, alışılmadık derecede pahalı jeton kullanımı, bağlam penceresi hataları, geri dönüş girişimleri ve manuel olarak hata ayıklama etiketli istekler için izlemeleri saklayın. Rutin başarılı trafiği daha düşük bir oranda örnekleyin. Bu, depolama hacmini kontrol ederken olayları açıklama olasılığı yüksek olan izleri tutar.

Makul bir politika modeli basittir: her zaman hataları koruyun, istekleri her zaman bir gecikme veya belirteç eşiğinin üzerinde tutun, her zaman hata ayıklama etiketli izleri tutun ve sıradan başarılı istekleri olasılıksal olarak örnekleyin. Trafik değiştikçe eşikleri tekrar ziyaret edin. Erken benimseme sırasında yararlı olan bir eşik, üretim trafiği büyüdüğünde çok düşük olabilir.

Telemetri için Sözleşme Testleri Ekle

Telemetri, API sözleşme gibi test edilmelidir çünkü aşağı yöndeki kontrol panelleri, uyarılar, maliyet kontrolleri ve olay iş akışları buna bağlıdır. Temsili ağ geçidi isteklerini çalıştıran ve gerekli aralıkların ve özniteliklerin yayınlandığını iddia eden testler ekleyin.

Testler, başarılı bir isteğin mantıksal LLM işlem aralığını, bir sağlayıcı deneme aralığını, istenen modeli, yanıt modelini, sağlayıcı adını, mevcut olduğunda belirteç sayımlarını, ekip veya anahtar kapsamı meta verilerini, rota politikası sürümünü ve son durumu yayınladığını doğrulamalıdır. Yeniden deneme testleri, deneme sayısını ve yeniden deneme nedenlerini belirtmelidir. Geri dönüş testleri hem başarısız girişimi hem de son başarılı sağlayıcı girişimini belirtmelidir. Doğrulama testleri şema kimliğini, doğrulama durumunu ve onarım girişimi sayısını belirtmelidir.

Güvenlik testleri de aynı derecede önemlidir. Dışa aktarılan telemetride ham sağlayıcı anahtarlarının, yetkilendirme başlıklarının, çerezlerin, ham istemlerin, ham tamamlamaların ve onaylanmamış müşteri tanımlayıcılarının bulunmadığını iddia edin.Bir geliştirici, sınıflandırmadan yeni bir yayılma özelliği eklediğinde bu testler başarısız olarak kapatılmalıdır.

Uygulama Kontrol Listesi

• Özellik sözleşmesi: Gerekli, isteğe bağlı, kısıtlı ve yasaklı özellikleri tanımlayın.
• Span hiyerarşisi: Ayrı gelen istekler, mantıksal LLM işlemleri, sağlayıcı girişimleri, yeniden denemeler, geri dönüşler, alma çağrıları, araç çağrıları ve doğrulama.
• Anlamsal eşleme: Uygun oldukları yerde OpenTelemetry GenAI niteliklerini ve sahiplik ve yönlendirme bağlamı için özel ağ geçidi niteliklerini kullanın.
• Gizlilik politikası: Bunun yerine varsayılan olarak karmaları, şablon kimliklerini, şema kimliklerini, araç adlarını, belirteç sayılarını, gecikmeyi ve hata sınıflarını kullanın ham içerik.
• Toplayıcı işlemciler: Yasaklanmış alanları silin, engellenen kalıpları düzenleyin, düşük riskli özellikleri izin verilenler listesine ekleyin ve hassas izleri ayrı ayrı yönlendirin.
• Örnekleme politikası: Yüksek değerli izleri kuyruk örneğiyle alın ve toplu metrikleri koruyun unsampled.
• Kontrol Panelleri: Gecikme, kullanım, hatalar, yeniden denemeler, geri dönüşler, doğrulama ve maliyet etkenleri hakkında görünümler oluşturun.
• Uyarılar: Normalleştirilmiş hata sınıfları, p99 gecikme değişimleri, yeniden deneme amplifikasyonu, geri dönüş ani artışları, doğrulama hataları ve belirteç anormallikleri.
• Sözleşme testleri: Gerekli telemetrinin mevcut olduğunu ve hassas telemetrinin bulunmadığını iddia edin.

Açıkça Karar Vermek İçin Takaslar

Ağ geçidi düzeyindeki araçlar, tutarlı meta verileri hızlı bir şekilde sağlar, ancak ekipler aşağıdakiler gibi yapılandırılmış istek meta verilerini iletmediği sürece uygulamaya özel bağlamı kaçırabilir kiracı, iş akışı, bilgi istemi şablonu ve özellik adı. Serbest biçimli günlüklere güvenmek yerine bu meta verileri ağ geçidi istek sözleşmesinin bir parçası haline getirin.

Tam içerik yakalama, hata ayıklamayı ve değerlendirmeyi iyileştirir ancak gizliliği, güvenliği, saklamayı ve erişim kontrolü yükünü artırır. Çoğu ekip yalnızca karmalar, şablon kimlikleri, şema kimlikleri ve düzeltilmiş alıntılarla başlamalıdır.

Sağlayıcıdan bağımsız hata sınıfları, kontrol panellerinin birden çok model API'sinde kullanılabilir olmasını sağlar, ancak sağlayıcıya özgü ayrıntıları sıkıştırır. Ham sağlayıcı hata kodlarını yalnızca güvenli olduğunda saklayın ve bunlara erişimi kısıtlayın.

OpenTelemetry GenAI kuralları bağımlı kalmayı azaltır, ancak kurallar gelişmeye devam edecektir. Dahili bir eşleyici, kararsız özellik adlarının kod tabanından sızmasına izin vermeden standartlaştırmanın avantajlarını sunar.

Sonuç

Sağlayıcıdan bağımsız LLM gözlemlenebilirliği yalnızca model çağrılarına eklenen izleme değildir. Bu, ağ geçidi katmanında bir işletim sözleşmesidir: tutarlı kapsamlar, normalleştirilmiş model ve sağlayıcı meta verileri, sahiplik bağlamı, belirteç kullanımı, yeniden deneme ve geri dönüş görünürlüğü, gizlilik kontrolleri, örnekleme kuralları ve hassas verilerin sızmasını önleyen testler.

Ağ geçidiyle başlayın çünkü ağ geçidi en önemli kararları zaten görür: isteği kim yaptı, hangi politika onu yönlendirdi, hangi sağlayıcı ona hizmet etti, belirteç maliyeti ne kadar oldu, ne kadar sürdü, kurtarma mantığının çalışıp çalışmadığı ve neyin başarısız olduğu. Bu temel istikrarlı hale geldikten sonra uygulama ekipleri, her ekibin kendi Yüksek Lisans gözlemlenebilirlik sistemini icat etmesine gerek kalmadan daha zengin iş akışı bağlamı ekleyebilir.

İlgili okuma

• geri dönüş yönlendirme telemetrisi