Kavramlar

Span

Span, tek bir iş birimidir. Bir adı, bir türü, bir başlangıç zamanı, çoğunlukla bir bitiş zamanı ve bir durumu vardır. Neyin girdiğini, neyin çıktığını, kaç token kullandığını, ne kadara mal olduğunu ve başarısız olduysa hatayı taşıyabilir.

Adı düşük kardinaliteli tutun. search_docs bir addır; search_docs(query=hello) ise birbirine yapıştırılmış bir ad ile bir değerdir ve iki çalıştırmanız olur olmaz ada göre gruplamayı işe yaramaz hâle getirir.

Trace

Trace, tek bir çalıştırmadan gelen bütün span'lerdir; onları 128 bitlik bir trace kimliği birleştirir. Trace'in içinde ağacın biçimini parent_span_id verir: bir model adımının içinde yapılan araç çağrısı o adımın çocuğudur, dolayısıyla ekrandaki iç içelik gerçekte olan iç içeliktir.

Kimlikler OpenTelemetry biçimindedir: bir trace için 32, bir span için 16 küçük harfli onaltılık karakter. Bu bir süs değildir. Web katmanınızda başlayıp ajanınızda biten bir trace'in ikisi boyunca tek bir trace kalmasını sağlayan da, mcpd'nin telemetrinizi zaten okuyan başka her şeyin yanında durabilmesini sağlayan da budur.

Üstü yabancı bir izleme sisteminden gelen bir span, üst kimliğini bunun yerine external_parent_span_id alanında taşır. mcpd bu değeri ilişkilendirme için saklar ama ağacını asla ondan kurmaz: mcpd'ye hiç ulaşmamış bir span'i adlandıran bir üst kimlik, bütün alt ağacı hiçbir şeyin altına asardı.

mcpd her trace'in bir izdüşümünü de saklar: span sayısı, hata sayısı, toplam token, toplam maliyet, kaç model çağrısı ve kaç araç çağrısı olduğu. Bu satır her yazmada artırılmaz, span'lerden yeniden hesaplanır; çünkü span'ler sırasız gelir, yeniden denenir ve yerinde güncellenir. Bir sayaç bu üçünün de altında kayar ve listede gözle görülür biçimde yanlış olan bir span sayısı, okuyanın sayfadaki başka her sayıya duyduğu güveni kırar.

Kök span'ler ve olay span'leri

Kök span, trace'in içinde üstü olmayan span'dir. Normalde bir agent_run ya da workflow_run span'idir; trace adını, etiketlerini ve ilişkilendirmesini oradan alır. Etiketler yalnızca kökte anlamlıdır, orada çalıştırmanın tamamını etiketler.

Olay span'i bir süre değil, zamanda bir noktadır; bu yüzden bitişi ve süresi yoktur. Akışla gelen bir parça olağan örnektir. Bu ayrım eksik bir bitiş zamanından çıkarılmaz, ayrıca saklanır; çünkü “bunun hiç bitişi olmadı” ile “bu henüz bitmedi” farklı olgulardır ve yalnızca biri sorundur.

Bir trace, kökü bittiğinde ve açık span kalmadığında tamamlanmış olur. O ana kadar gizlenmez; elde olan en iyi adla listede durur. Hiç bitmemiş çalıştırma, çoğu zaman bakmaya geldiğiniz çalıştırmadır.

Span türü

Tür, bir işlemin ne olduğunu söyler. Span'in nasıl çizileceğine, üzerinde hangi özniteliklerin anlam taşıdığına ve maliyet muhasebesinin ona bakıp bakmayacağına karar verir. mcpd, aileler hâlinde 33 tür tanımlar:

Dört tür token faturalandırır: model_generation, model_step, model_inference ve rag_embedding. Maliyet muhasebesinin okuduğu span'ler bunlardır. generic her zaman geçerlidir ve asla çıkarımla atanmaz; böylece mcpd'nin sınıflandıramadığı bir span tahmin edilmek yerine dürüstçe etiketlenir. Veri modeli, her türü ne anlama geldiğiyle birlikte listeler.

Model hiyerarşisi

Bu türlerden dördü iç içe geçer ve bu iç içelik modeldeki en yararlı şeydir:

• model_generation, mantıksal tek bir üretimdir: ilk istekten son yanıta kadar her şey.
• model_step, onun içindeki tek bir adımdır. İki kez araç çağıran bir üretimin üç adımı olur.
• model_inference, yalnızca sağlayıcıya gidiş dönüştür; içinde işlemci de araç yürütmesi de yoktur.
• model_chunk, akışla gelen tek bir parçadır ve olay olarak kaydedilir.

Tek yerine dört katmanın nedeni, “model çağrısı yavaştı” cümlesinin söylendiği hâliyle neredeyse hiç doğru olmamasıdır. İşin içine araçlar girdiğinde kodunuzdan yapılan tek bir çağrı tek bir HTTP gidiş dönüşü değildir: bir istek, bir araç, bir istek daha, bir guardrail, bir istek daha. Bunu tek bir span'e indirirseniz, altı saniyeyi kendi yeniden deneme döngünüzde geçiren bir çalıştırma, altı saniyeyi sağlayıcıyı beklemekle geçirenden ayırt edilemez. Çıkarımı adımdan, adımı üretimden ayırmak farkı okunur kılar; ilk parça olayı da size ilk token'a kadar geçen süreyi verir.

Token kullanımını bir kez, sağlayıcı çağrısını yapan span'de kaydedin. Trace izdüşümü, girdi ve çıktı token'larını trace'teki her span üzerinden toplar; aynı sayıları hem bir üretime hem de onun her adımına iliştirirseniz ekrandaki token toplamı da maliyet de ikiye katlanır. Hiyerarşi zamanlama içindir; token'lar, sağlayıcıyla gerçekte konuşan katmana aittir.

Altı sinyal

Span'ler, mcpd'nin sakladığı altı şeyden biridir. Loglar, bir çalıştırmanın ürettiği satırlardır. Metrikler; sayaç, gösterge ya da histogram biçiminde sayısal gözlemlerdir. Puanlar, bir span'in ya da bir trace'in makine değerlendirmesidir. Geri bildirim ise insanın değerlendirmesidir. Yön notu, bitmiş bir çalıştırma hakkında yazılmış tek cümledir. Çoğunu bir model yazar. outcome notlarını ise daemon, çalıştırmanın durumundan ve elinde zaten bulunan diğer bilgilerden yazar.

Altısı da ait oldukları trace kimliğini, çoğu ayrıca span kimliğini taşır ve hiçbir şey yazılmadan önce altısı da aynı maskeleme hattından geçer. Bir sır, bir log satırından da tıpkı bir prompt'tan sızdığı kadar iyi sızar.

Bir puan her zaman ölçeğini bildirir: değeri ile arasında durduğu en küçük ve en büyük değer. Her SDK ikisini de çağrı yerinde ister; çünkü ölçeği iliştirilmemiş çıplak bir 0.7, aynı puanlayıcının geçen haftaki çıktısı dahil hiçbir şeyle karşılaştırılamaz.

Geri bildirim, puanlardan ayrı bir yerde tutulur ve onlarla asla ortalanmaz. Beş biçimde gelir: thumbs, rating, correction, tag ve comment. Beşinin en değerlisi düzeltmedir, çünkü doğru yanıtı taşıyan tek sinyal odur.

İlişkilendirme

İlişkilendirme, bir sinyalin ait olduğu bağlamdır. Bir yığın çalıştırma ile dilimleyebileceğiniz bir küme arasındaki fark budur.

Zorunlu tek alan project alanıdır. Gönderen bir proje adı vermediğinde daemon sinyali --project varsayılanının altına yazar; böylece hiçbir şey ait olacak bir yeri olmadan saklanmaz.

Gereksiz göründüğünde bile session_id alanını doldurun. Bir ajan çalıştırması bir trace'tir, ama şikâyet neredeyse her zaman bir konuşma hakkındadır; oturum kimliği olmadan on bir ayrı trace'i kişinin gerçekte yaşadığı alışverişe geri çevirecek hiçbir şey yoktur.

Trace listesi environment, session_id, thread_id ve user_id alanlarına doğrudan filtre uygular; yanında durum, tür, ad, etiketler, model, zaman aralığı, en küçük süre, en küçük maliyet ve puan da vardır. Çalıştırma bulma hepsini bir araya getirir.

Bağlar

Bir span'in tek bir üstü ve istediğiniz kadar bağı olur. Bir bağ, başka bir span'i ya da başka bir trace'i gösterir ve nedenini söyler: follows_from, retry_of, replay_of ya da siz ne ad verirseniz.

Bağlar, üstlük ilişkisi çoktan teke toplanmayı anlatamadığı için vardır. Yirmi isteğin yol açtığı bir toplu işin yirmi bağı ve bir üstü olur. Bunu ağaca zorlamak ya on dokuz kopya alt ağaç uydururdu ya da nedenlerin on dokuzunu atardı.

Sırada

• Her varlık ve her alan eksiksiz: Veri modeli.
• Bu sözcüklerin kodda nasıl göründüğü: SDK'lar.
• Span'ler OTLP olarak geldiğinde mcpd'nin neleri çıkardığı: OpenTelemetry.
• Sözcükleri bir sorguya çevirmek: Çalıştırma bulma.