MLflow Tracing ile ajana gözlemlenebilirlik

Bu makalede, Databricks üzerinde MLflow İzleme ile üretken yapay zeka uygulamalarınıza gözlemlenebilirlik ekleme adımları açıklanmaktadır.

MLflow İzleme nedir?

MLflow İzleme, geliştirmeden dağıtıma kadar üretken yapay zeka uygulamaları için uçtan uca gözlemlenebilirlik sağlar. İzleme, Databricks'in nesil yapay zeka araç takımıyla tamamen tümleşiktir ve geliştirme ve üretim yaşam döngüsünün tamamında ayrıntılı içgörüler elde eder.

Nesil yapay zeka uygulamalarında izleme için önemli kullanım örnekleri aşağıdadır:

• Kolaylaştırılmış hata ayıklama: İzleme, genel yapay zeka uygulamanızın her adımında görünürlük sağlayarak sorunları tanılamayı ve çözmeyi kolaylaştırır.

• Çevrimdışı değerlendirme: İzleme aracı değerlendirmesi için değerli veriler oluşturur ve zaman içinde aracıların kalitesini ölçmenize ve geliştirmenize olanak sağlar.

• Üretim izleme: İzleme aracı davranışına ve ayrıntılı yürütme adımlarına görünürlük sağlayarak üretimde aracı performansını izlemenizi ve iyileştirmenizi sağlar.

• Denetim günlükleri: MLflow İzleme aracı eylemlerinin ve kararlarının kapsamlı denetim günlüklerini oluşturur. Bu, uyumluluk sağlamak ve beklenmeyen sorunlar ortaya çıktığında hata ayıklamayı desteklemek için çok önemlidir.

Gereksinimler

MLflow İzleme, MLflow 2.13.0 ve üzeri sürümlerde kullanılabilir. Databricks, en son özelliklere ve iyileştirmelere erişmek için MLflow'un en son sürümünün yüklenmesini önerir.

%pip install mlflow>=2.13.0 -qqqU
%restart_python

Otomatik İzleme

MLflow otomatik günlük kaydı , bir satır kod ekleyerek aracınızı hızla donatmanızı sağlar. mlflow.<library>.autolog()

MLflow, en popüler acente yazma kitaplıkları için otomatik günlüklemeyi destekler. Her yazma kitaplığı hakkında daha fazla bilgi için MLflow otomatik kaydetme belgelerine bakın:

Otomatik kaydetmeyi devre dışı bırakma

Aşağıdaki kitaplıklar için Databricks Runtime 15.4 ML ve üzerinde otomatik kaydetme izlemesi varsayılan olarak etkindir:

• LangChain
• Langgraph
• OpenAI
• LlamaIndex

Bu kitaplıklarda otomatik kaydetme izlemeyi devre dışı bırakmak için not defterinde aşağıdaki komutu çalıştırın:

`mlflow.<library>.autolog(log_traces=False)`

İzlemeleri el ile ekleme

Otomatik kaydetme aracıları izlemenin kullanışlı bir yolunu sağlarken, aracınızı daha ayrıntılı bir şekilde izlemek veya otomatik kaydetmenin yakalamadığı ek izlemeler eklemek isteyebilirsiniz. Bu gibi durumlarda, izlemeleri el ile eklemek için MLflow İzleme API'lerini kullanın.

MLflow İzleme API'leri, izlemenin ağaç yapısını yönetme konusunda endişelenmeden izleme eklemek için düşük kodlu API'lerdir. MLflow, Python yığınını kullanarak uygun üst-alt span ilişkilerini otomatik olarak belirler.

Otomatik kaydetme ve el ile izlemeyi birleştirme

Otomatik kaydetme ile manuel izleme API'leri kullanılabilir. MLflow, otomatik kaydetme ve el ile izleme tarafından oluşturulan aralıkları birleştirerek aracınızın yürütülmesinin tam bir izlemesini oluşturur. Otomatik kaydetme ve el ile izlemeyi birleştirme örneği için MLflow İzleme ile aracı çağıran bir aracı izlemebölümüne bakın.

@mlflow.trace dekoratörünü kullanarak işlevleri izleme

Kodunuzu el ile izlemenin en basit yolu, bir işlev üzerine @mlflow.trace dekoratörü uygulamaktır. MLflow izleme dekoratörü, bir izlemedeki yürütme birimini temsil eden ve izleme görselleştirmesinde tek bir satır olarak görüntülenen, süslü işlevin kapsamına sahip bir "span" oluşturur. span işlevin giriş ve çıkışını, gecikme süresini ve işlevden tetiklenen özel durumları yakalar.

Örneğin, aşağıdaki kod, giriş bağımsız değişkenleri x ve y ile çıkışı yakalayan my_function adlı bir span oluşturur.

import mlflow

@mlflow.trace
def add(x: int, y: int) -> int:
  return x + y

Ayrıca span adını, span türünü özelleştirebilir ve span'a özel öznitelikler ekleyebilirsiniz:

from mlflow.entities import SpanType

@mlflow.trace(
  # By default, the function name is used as the span name. You can override it with the `name` parameter.
  name="my_add_function",
  # Specify the span type using the `span_type` parameter.
  span_type=SpanType.TOOL,
  # Add custom attributes to the span using the `attributes` parameter. By default, MLflow only captures input and output.
  attributes={"key": "value"}
)
def add(x: int, y: int) -> int:
  return x + y

Bağlam yöneticisini kullanarak rastgele kod bloklarını izleme

Yalnızca bir işlev değil, rastgele bir kod bloğu için bir yayılma alanı oluşturmak için mlflow.start_span() kod bloğunu sarmalayan bir bağlam yöneticisi olarak kullanın. Süreç, bağlam girildiğinde başlar ve bağlamdan çıkıldığında biter. Span girişi ve çıkışları, bağlam yöneticisi tarafından sağlanan span nesnesinin ayarlayıcı yöntemleri kullanılarak el ile sağlanmalıdır. Daha fazla bilgi için bkz. MLflow belgeleri - bağlam işleyicisi.

with mlflow.start_span(name="my_span") as span:
  span.set_inputs({"x": x, "y": y})
  result = x + y
  span.set_outputs(result)
  span.set_attribute("key", "value")

Alt seviye izleme kütüphaneleri

MLflow ayrıca izleme ağacı yapısını açıkça denetlemek için alt düzey API'ler sağlar. MLflow belgelerine bakın - Manuel Enstrümantasyon.

İzleme örneği: Otomatik kaydetme ve el ile izlemeleri birleştirme

Aşağıdaki örnek, OpenAI otomatik kaydetmeyi ve manuel izlemeyi birleştirerek bir araç çağırma aracısının tam anlamıyla enstrümanlanmasını sağlar.

import json
from openai import OpenAI
import mlflow
from mlflow.entities import SpanType

client = OpenAI()

# Enable OpenAI autologging to capture LLM API calls
# (*Not necessary if you are using the Databricks Runtime 15.4 ML and above, where OpenAI autologging is enabled by default)
mlflow.openai.autolog()

# Define the tool function. Decorate it with `@mlflow.trace` to create a span for its execution.
@mlflow.trace(span_type=SpanType.TOOL)
def get_weather(city: str) -> str:
  if city == "Tokyo":
    return "sunny"
  elif city == "Paris":
    return "rainy"
  return "unknown"


tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
      },
    },
  }
]

_tool_functions = {"get_weather": get_weather}

# Define a simple tool-calling agent
@mlflow.trace(span_type=SpanType.AGENT)
def run_tool_agent(question: str):
  messages = [{"role": "user", "content": question}]

  # Invoke the model with the given question and available tools
  response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    tools=tools,
  )
  ai_msg = response.choices[0].message
  messages.append(ai_msg)

  # If the model requests tool calls, invoke the function(s) with the specified arguments
  if tool_calls := ai_msg.tool_calls:
    for tool_call in tool_calls:
      function_name = tool_call.function.name
      if tool_func := _tool_functions.get(function_name):
        args = json.loads(tool_call.function.arguments)
        tool_result = tool_func(**args)
      else:
        raise RuntimeError("An invalid tool is returned from the assistant!")

      messages.append(
        {
          "role": "tool",
          "tool_call_id": tool_call.id,
          "content": tool_result,
        }
      )

    # Send the tool results to the model and get a new response
    response = client.chat.completions.create(
      model="gpt-4o-mini", messages=messages
    )

  return response.choices[0].message.content

# Run the tool calling agent
question = "What's the weather like in Paris today?"
answer = run_tool_agent(question)

İzleri etiketlerle işaretleme

MLflow izleme etiketleri konuşma kimliği, kullanıcı kimliği, Git işleme karması gibi izlemelere özel meta veriler eklemenize olanak sağlayan anahtar-değer çiftleridir. Etiketler, izlemeleri filtrelemek ve aramak için MLflow kullanıcı arabiriminde görüntülenir.

Etiketler, MLflow API'leri veya MLflow kullanıcı arabirimi kullanılarak devam eden veya tamamlanmış bir izleme olarak ayarlanabilir. Aşağıdaki örnek, mlflow.update_current_trace() API'sini kullanarak devam eden bir izlemeye etiket eklemeyi gösterir.

@mlflow.trace
def my_func(x):
    mlflow.update_current_trace(tags={"fruit": "apple"})
    return x + 1

İzlemeleri etiketleme ve izlemeleri filtrelemek ve aramak için bunları kullanma hakkında daha fazla bilgi edinmek için bkz. MLflow belgeleri - İzleme Etiketlerini Ayarlama.

İzleri gözden geçirme

Aracıyı çalıştırdıktan sonra izlemeleri gözden geçirmek için aşağıdaki seçeneklerden birini kullanın:

• Satır içi görselleştirme: Databricks not defterlerinde izler hücre çıkışında satır içi gösterilir.
• MLflow denemesi: Databricks'te Denemeler> bir deneme seçin >İzlemeler kısmına giderek bir deneme için tüm izlemeleri görüntüleyebilir ve arayabilirsiniz.
• MLflow çalıştırması: Aracı etkin bir MLflow Çalıştırması altında çalıştığında, MLflow kullanıcı arabiriminin Çalıştır sayfasında izlemeler görünür.
• Aracı Değerlendirme Kullanıcı Arabirimi: Mozaik AI Aracısı Değerlendirmesi'nde, değerlendirme sonucunda her aracı yürütmesinin izlerini gözden geçirmek için Ayrıntılı iz görünümünü gör seçeneğine tıklayabilirsiniz.
• İzleme Arama API'sini: İzlemeleri program aracılığıyla almak için İzleme Arama API'sinikullanın.

İzlemeleri kullanarak ajanları değerlendirme

İzleme verileri, aracılarınızı değerlendirmek için değerli bir kaynak görevi görür. Modellerinizin yürütülmesiyle ilgili ayrıntılı bilgileri yakalayarak, MLflow İzleme çevrimdışı değerlendirmede etkili bir işlemdir. Aracınızın performansını altın bir veri kümesine göre değerlendirmek, sorunları belirlemek ve aracınızın performansını geliştirmek için izleme verilerini kullanabilirsiniz.

%pip install -U mlflow databricks-agents
%restart_python

import mlflow

# Get the recent 50 successful traces from the experiment
traces = mlflow.search_traces(
    max_results=50,
    filter_string="status = 'OK'",
)

traces.drop_duplicates("request", inplace=True) # Drop duplicate requests.
traces["trace"] = traces["trace"].apply(lambda x: x.to_json()) # Convert the trace to JSON format.

# Evaluate the agent with the trace data
mlflow.evaluate(data=traces, model_type="databricks-agent")

Aracı değerlendirmesi hakkında daha fazla bilgi edinmek için bkz. Değerlendirme yürütme vesonuçları inceleme.

Çıkarım tablolarıyla dağıtılan aracıları izleyin

Bir aracı Mozaik Yapay Zeka Modeli Sunma'ya dağıtıldıktan sonra aracıyı izlemek için çıkarım tablolarını kullanabilirsiniz. Çıkarım tabloları, gözden geçirme uygulamasından gelen isteklerin, yanıtların, aracı izlemelerinin ve aracı geri bildirimlerinin ayrıntılı günlüklerini içerir. Bu bilgiler, sorunları ayıklamanıza, performansı izlemenize ve çevrimdışı değerlendirme için altın renkli bir veri kümesi oluşturmanıza olanak tanır.

Yapay zeka aracıları dağıtımlarında çıkarım tablolarını etkinleştirmek için bkz. Yapay zeka aracıları için çıkarım tablolarını etkinleştirme.

Çevrimiçi izleri sorgula

Çıkarım tablosunu sorgulamak ve sonuçları analiz etmek için bir not defteri kullanın.

İzlemeleri görselleştirmek için display(<the request logs table>) çalıştırın ve incelemek üzere satırları seçin:

# Query the inference table
df = spark.sql("SELECT * FROM <catalog.schema.my-inference-table-name>")
display(df)

Ajanları izleyin

Bkz. Genel yapay zeka uygulamanızı nasıl izlersiniz.

Ek yük gecikme süresini izleme

İzlemeler, performans etkisini en aza indirmek için zaman uyumsuz olarak yazılır. Ancak izleme, özellikle her çıkarım isteğinin iz boyutu büyük olduğunda uç nokta yanıt hızına gecikme ekler. Databricks, üretime dağıtmadan önce izleme gecikmesi etkilerini anlamak için uç noktanızı test etmenizi önerir.

Aşağıdaki tablo, izleme boyutuna göre gecikme süresi etkisine yönelik kaba tahminler sağlar:

Sorun giderme

Sorun giderme ve sık sorulan sorular için MLflow belgelerine bakın: nasıl yapılır kılavuzu ve MLflow belgeleri: SSS