Waarneembaarheid van agents met MLflow-tracering

In dit artikel wordt beschreven hoe u waarneembaarheid toevoegt aan uw generatieve AI-toepassingen met MLflow Tracing op Databricks.

Wat is MLflow Tracing?

MLflow Tracing biedt end-to-end waarneembaarheid voor generatieve AI-toepassingen van ontwikkeling tot implementatie. Traceren is volledig geïntegreerd met de gen AI-toolset van Databricks, waarbij gedetailleerde inzichten worden vastgelegd over de volledige ontwikkelings- en productielevenscyclus.

Hier volgen de belangrijkste use cases voor tracering in gen AI-toepassingen:

• Gestroomlijnde foutopsporing: Tracering biedt inzicht in elke stap van uw GEN AI-toepassing, waardoor het diagnosticeren en oplossen van problemen eenvoudiger wordt.

• offline evaluatie: tracering genereert waardevolle gegevens voor de evaluatie van agents, zodat u de kwaliteit van agents in de loop van de tijd kunt meten en verbeteren.

• Productiebewaking: Tracering biedt inzicht in agentgedrag en gedetailleerde uitvoeringsstappen, zodat u de prestaties van agents in productie kunt bewaken en optimaliseren.

• auditlogboeken: MLflow Tracing genereert uitgebreide auditlogboeken van agentacties en beslissingen. Dit is essentieel voor het waarborgen van naleving en het ondersteunen van foutopsporing wanneer er onverwachte problemen optreden.

Vereisten

MLflow Tracing is beschikbaar op MLflow-versies 2.13.0 en hoger. Databricks raadt aan de nieuwste versie van MLflow te installeren voor toegang tot de nieuwste functies en verbeteringen.

%pip install mlflow>=2.13.0 -qqqU
%restart_python

automatische tracering

automatische logboeken van MLflow kunt u uw agent snel instrumenteren door één regel aan uw code toe te voegen, mlflow.<library>.autolog().

MLflow biedt ondersteuning voor autologging voor de populairste agentontwerpbibliotheken. Zie de MLflow-autologging documentatievoor meer informatie over elke auteursbibliotheek.

Bibliotheek	Ondersteuning voor autologgingversie	Opdracht Voor automatisch inloggen
LangChain	0.1.0 ~ Meest recente	mlflow.langchain.autolog()
Langgraph	0.1.1 ~ Meest recente	mlflow.langgraph.autolog()
OpenAI	1.0.0 ~ Laatste	mlflow.openai.autolog()
LlamaIndex	0.10.44 ~ Nieuwste	mlflow.llamaindex.autolog()
DSPy	2.5.17 ~ Laatste versie	mlflow.dspy.autolog()
Amazon Bedrock	1.33.0 ~ Laatste (boto3)	mlflow.bedrock.autolog()
Antropisch	0.30.0 ~ Laatste	mlflow.anthropic.autolog()
AutoGen	0.2.36 ~ 0,2.40	mlflow.autogen.autolog()
Google Gemini	1.0.0 ~ Laatste	mlflow.gemini.autolog()
CrewAI	0.80.0 ~ Meest recente	mlflow.crewai.autolog()
LiteLLM	1.52.9 ~ Laatste	mlflow.litellm.autolog()
Groq	0.13.0 ~ Meest recente	mlflow.groq.autolog()
Mistral	1.0.0 ~ Laatste	mlflow.mistral.autolog()

Automatisch logboeken uitschakelen

Automatische logboektracering is standaard ingeschakeld in Databricks Runtime 15.4 ML en hoger voor de volgende bibliotheken:

• LangChain
• Langgraph
• OpenAI
• LlamaIndex

Als u automatische logboektracering voor deze bibliotheken wilt uitschakelen, voert u de volgende opdracht uit in een notebook:

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

Handmatig traceringen toevoegen

Hoewel autologging een handige manier biedt om agents te instrumenteren, wilt u uw agent mogelijk gedetailleerder instrumenteren of extra traceringen toevoegen die niet worden vastgelegd door autologging. In deze gevallen gebruikt u MLflow Tracing-API's om handmatig traceringen toe te voegen.

MLflow Tracing-API's zijn API's met weinig code voor het toevoegen van traceringen zonder dat u zich zorgen hoeft te maken over het beheren van de structuur van de trace. MLflow bepaalt automatisch de juiste ouder-kind span-relaties met behulp van de Python-stack.

Autologging en handmatige tracering combineren

Handmatige tracerings-API's kunnen worden gebruikt met automatische aanmelding. MLflow combineert de spans die zijn gecreëerd door autologging en handmatige tracering om een volledige trace van de uitvoering van uw agent te maken. Zie Instrumenteren van een hulpmiddeloproepende agent met MLflow Tracingvoor een voorbeeld van het combineren van autologging en handmatige tracering.

Functies traceren met behulp van de @mlflow.trace decorator

De eenvoudigste manier om uw code handmatig te instrumenteren is door een functie te versieren met de @mlflow.trace decorator. De MLflow-traceringsdecorator creëert een "span" met de scope van de gedecoreerde functie, die een uitvoeringseenheid in een trace vertegenwoordigt en als een enkele rij wordt weergegeven in de traceringsvisualisatie. De periode legt de invoer en uitvoer van de functie, latentie en eventuele uitzonderingen die zijn gegenereerd door de functie vast.

Met de volgende code wordt bijvoorbeeld een span gemaakt met de naam my_function waarmee invoerargumenten worden vastgelegd x en y en de uitvoer.

import mlflow

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

U kunt ook de naam, het type en aangepaste kenmerken van de span aanpassen:

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

Willekeurige codeblokken traceren met contextbeheer

Als u een bereik wilt maken voor een willekeurig codeblok, niet alleen voor een functie, gebruikt u mlflow.start_span() als contextbeheer waarmee het codeblok wordt verpakt. De periode begint wanneer de context wordt ingevoerd en eindigt wanneer de context wordt afgesloten. De spaninvoer en uitvoer moeten handmatig worden opgegeven met behulp van settermethoden van het spanobject dat door de contextbeheerder wordt gegenereerd. Zie MLflow-documentatie - contexthandlervoor meer informatie.

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")

Traceringsbibliotheken op lager niveau

MLflow biedt ook API's op laag niveau voor het expliciet beheren van de structuur van de traceringsstructuur. Zie MLflow-documentatie - Handmatige instrumentatie.

voorbeeld van tracering: Autologging en handmatige traceringen combineren

In het volgende voorbeeld worden automatische logboeken en handmatige tracering van OpenAI gecombineerd om een agent voor het aanroepen van hulpprogramma's volledig te instrumenteren.

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)

Aantekeningen toevoegen aan traceringen met tags

MLflow-traceringstags sleutel-waardeparen zijn waarmee u aangepaste metagegevens kunt toevoegen aan traceringen, zoals een gespreks-id, een gebruikers-id, Git-doorvoerhash, enzovoort. Tags worden weergegeven in de MLflow-gebruikersinterface om traceringen te filteren en te doorzoeken.

Tags kunnen worden ingesteld op een doorlopende of voltooide trace met behulp van MLflow-API's of de gebruikersinterface van MLflow. In het volgende voorbeeld ziet u hoe u een tag toevoegt aan een doorlopende trace met behulp van de mlflow.update_current_trace()-API.

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

Zie MLflow-documentatie - Traceringstags instellenvoor meer informatie over het taggen van traceringen en hoe u deze kunt gebruiken om traceringen te filteren en te doorzoeken.

Traceringen bekijken

Als u traceringen wilt controleren nadat de agent is uitgevoerd, kunt u een van de volgende opties gebruiken:

• Inline-visualisatie: In Databricks-notebooks worden traces inline weergegeven in de celuitvoer.
• MLflow-experiment: ga in Databricks naar Experimenten> Selecteer een experiment >Traces om alle traceringen voor een experiment te bekijken en te doorzoeken.
• MLflow Run: Wanneer de agent wordt uitgevoerd in een actieve MLflow Run, verschijnen de traceringen op de pagina Run van de MLflow-gebruikersinterface.
• Agent Evaluation UI: In Mosaic AI Agent Evaluation kunt u traceringen bekijken voor elke agentuitvoering door te klikken op Gedetailleerde traceringsweergave bekijken in het evaluatieresultaat.
• traceringszoekopdrachten-API: als u traceringen programmatisch wilt ophalen, gebruikt u de traceringszoekopdrachten-API.

Agents evalueren met behulp van traceringen

Traceringsgegevens dienen als een waardevolle bron voor het evalueren van uw medewerkers. Door gedetailleerde informatie over de uitvoering van uw modellen vast te leggen, is MLflow Tracing een instrument voor offline evaluatie. U kunt de traceringsgegevens gebruiken om de prestaties van uw agent te evalueren op basis van een gouden gegevensset, problemen te identificeren en de prestaties van uw agent te verbeteren.

%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")

Zie Een evaluatie uitvoeren en de resultaten bekijkenvoor meer informatie over agentevaluatie.

Ingezette agents bewaken met inferentietabellen

Nadat een agent is geïmplementeerd in Mosaic AI Model Serving, kunt u deductietabellen gebruiken om de agent te bewaken. De inferentietabellen bevatten gedetailleerde logboeken met aanvragen, antwoorden, agenttraceringen en feedback van de agent in de beoordelingsapplicatie. Met deze informatie kunt u problemen opsporen, prestaties bewaken en een gouden gegevensset maken voor offline evaluatie.

Zie Deductietabellen inschakelen voor AI-agentsom deductietabellen in te schakelen voor agentimplementaties.

Online traceringen opvragen

Gebruik een notebook om een query uit te voeren op de deductietabel en de resultaten te analyseren.

Als u traceringen wilt visualiseren, voert u display(<the request logs table>) uit en selecteert u rijen om te controleren:

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

Agents controleren

Zie Hoe uw gen AI-app te bewaken.

Overheadlatentie traceren

Traceringen worden asynchroon geschreven om de prestatie-impact te minimaliseren. Tracering voegt echter nog steeds latentie toe aan de reactiesnelheid van eindpunten, met name wanneer de traceringsgrootte voor elke deductieaanvraag groot is. Databricks raadt u aan uw eindpunt te testen om inzicht te hebben in de gevolgen van de traceringslatentie voordat deze in productie wordt geïmplementeerd.

De volgende tabel bevat ruwe schattingen voor latentie-effect door traceringsgrootte.

Traceringsgrootte per aanvraag	Invloed op latentie van reactiesnelheid (ms)
~10 kB	~ 1 ms
~ 1 MB	50 ~ 100 ms
10 MB	150 ms ~

Problemen oplossen

Zie de documentatie voor MLflow voor probleemoplossing en veelgestelde vragen: Handleiding voor tracering en MLflow: Veelgestelde vragen