Ügynök megfigyelhetősége az MLflow-nyomkövetéssel

Ez a cikk bemutatja, hogyan adhat megfigyelhetőséget a generatív AI-alkalmazásokhoz az MLflow Tracing on Databricks használatával.

Mi az MLflow Tracing?

MLflow Tracing a fejlesztéstől az üzembe helyezésig átfogó megfigyelhetőséget biztosít a generatív AI-alkalmazások számára. A nyomkövetés teljes mértékben integrálva van a Databricks gen AI-eszközkészletével, és részletes elemzéseket készít a teljes fejlesztési és éles életciklusról.

A gen AI-alkalmazásokban a nyomkövetés legfontosabb használati esetei a következők:

• Egyszerűsített hibakeresési: A nyomkövetés áttekinthetővé teszi a gen AI-alkalmazás minden lépését, egyszerűbbé téve a problémák diagnosztizálását és megoldását.

• Offline kiértékelés: A nyomkövetés értékes adatokat generál az ügynökök kiértékeléséhez, amely lehetővé teszi az ügynökök minőségének időbeli mérését és javítását.

• Termelésmonitorozás: A követés betekintést nyújt az ügynökök viselkedésébe, valamint a részletes végrehajtási lépésekbe, lehetővé téve az ügynökök teljesítményének nyomon követésére és optimalizálására az éles környezetben.

• Audit naplók: Az MLflow Tracing az ügynök műveletei és döntései átfogó naplóit hozza létre. Ez elengedhetetlen a megfelelőség biztosításához és a hibakeresés támogatásához váratlan problémák esetén.

Követelmények

Az MLflow-nyomkövetés az MLflow 2.13.0-s és újabb verzióiban érhető el. A Databricks az MLflow legújabb verziójának telepítését javasolja a legújabb funkciók és fejlesztések eléréséhez.

%pip install mlflow>=2.13.0 -qqqU
%restart_python

Automatikus nyomkövetés

Az MLflow automatikus naplózása lehetővé teszi a szoftver ügynök gyors konfigurálását azáltal, hogy egyetlen sort ad hozzá a kódhoz, mlflow.<library>.autolog().

Az MLflow támogatja a legnépszerűbb ügynökfejlesztő könyvtárak automatikus naplózását. További információért az egyes szerzői kódtárakról lásd: MLflow autologging dokumentációja.

Automatikus kitöltés letiltása

Az automatikus nyomkövetés alapértelmezés szerint engedélyezve van a Databricks Runtime 15.4 ML-ben és újabb verziókban a következő kódtárak esetében:

• LangChain
• Langgraph
• OpenAI
• LlamaIndex

A kódtárak automatikus nyomkövetésének letiltásához futtassa a következő parancsot egy jegyzetfüzetben:

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

Nyomkövetések manuális hozzáadása

Bár az autologging kényelmes módot kínál az ügynökök műszerezésére, előfordulhat, hogy az ügynökét részletesebben szeretné műszerezni, vagy olyan további nyomkövetéseket szeretne hozzáadni, amelyeket az autologging nem rögzít. Ezekben az esetekben az MLflow Tracing API-kkal manuálisan adhat hozzá nyomkövetéseket.

MLflow Tracing API-k alacsony kódú API-k a nyomkövetések hozzáadásához anélkül, hogy a nyomkövetés faszerkezetének kezelésével kellene foglalkozniuk. Az MLflow automatikusan meghatározza a megfelelő szülő-gyermek összefüggéseket a Python verem segítségével.

Automatikus és manuális nyomkövetés kombinálása

A manuális nyomkövetési API-k használhatók az automatikus naplózással. Az MLflow egyesíti az automatikus és manuális nyomkövetés által létrehozott időtartamokat az ügynök végrehajtásának teljes nyomon követéséhez. Az automatikus naplózás és a manuális nyomkövetés kombinálására példa: egy eszközhívó ügynök instrumentálása az MLflow nyomkövetéssel .

Kövesd nyomon a függvényeket a @mlflow.trace dekorátor használatával

A kód manuális instrukciójának legegyszerűbb módja, ha egy függvényt a @mlflow.trace dekoratőrrel lát el. A MLflow nyomkövetési dekorátor létrehoz egy "span"-t a dekorált függvény hatókörével, amely egy végrehajtási egységet jelöl egy nyomkövetésben, és egyetlen sorként jelenik meg a nyomkövetési vizualizációban. A span rögzíti a függvény bemenetét és kimenetét, a késést és a függvényből eredő kivételeket.

Az alábbi kód például egy my_function nevű spant hoz létre, amely rögzíti a bemeneti argumentumokat x és y, valamint a kimenetet.

import mlflow

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

Testre is szabhatja a span nevét, a span típusát, és egyéni attribútumokat adhat hozzá a spanhoz:

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

Tetszőleges kódblokkok nyomkövetése a Context Manager használatával

Ha nem csak függvényt, hanem tetszőleges kódblokkot szeretne létrehozni, használja a mlflow.start_span() környezetkezelőként, amely a kódblokkot burkolja. A span akkor kezdődik, amikor belépünk a környezetbe, és amikor kilépünk a környezetből, ér véget. A span bemenetet és kimeneteket manuálisan kell megadni a környezetkezelő által biztosított span objektum setter metódusával. További információ: MLflow dokumentáció – környezetkezelő.

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

Alacsonyabb szintű nyomkövetési könyvtárak

Az MLflow alacsony szintű API-kat is biztosít a nyomkövetési fa szerkezetének explicit szabályozásához. Lásd a MLflow dokumentációt – Kézi instrumentáció.

Nyomkövetési példa: Automatikus és manuális nyomkövetések kombinálása

Az alábbi példa az OpenAI autologging és manuális nyomkövetés kombinációját használja egy eszközhívási ügynök teljes körű felszerelésére.

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)

Nyomkövetések jegyzetelése címkékkel

MLflow nyomkövetési címkék kulcs-érték párok, amelyek lehetővé teszik egyéni metaadatok hozzáadását a nyomkövetésekhez, például beszélgetésazonosítót, felhasználói azonosítót, Git commit kivonatot stb. A címkék az MLflow felhasználói felületén jelennek meg a nyomkövetések szűréséhez és kereséséhez.

A címkék egy folyamatban lévő vagy befejezett nyomkövetésre állíthatók be az MLflow API-k vagy az MLflow felhasználói felület használatával. Az alábbi példa bemutatja, hogy a mlflow.update_current_trace() API használatával címkét adhat hozzá egy folyamatban lévő nyomkövetéshez.

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

A nyomkövetések címkézéséről és a nyomkövetések szűrésére és keresésére való használatáról további információt MLflow dokumentációjában talál – Nyomkövetési címkék beállítása.

Nyomkövetések áttekintése

Az ügynök futtatása után a nyomkövetések áttekintéséhez használja az alábbi lehetőségek egyikét:

• Beágyazott vizualizálás: A Databricks-jegyzetfüzetekben a nyomvonalak közvetlenül jelennek meg a cellakimenetben.
• MLflow-kísérlet: A Databricksben lépjen a Kísérletekrészre, és> válasszon ki egy kísérletet. Használja aNyomkövetéseket > az összes nyomkövetés megtekintéséhez és kereséséhez az adott kísérlethez.
• MLflow-futtatási: Amikor az ügynök aktív MLflow-futtatás alatt fut, a nyomkövetések megjelennek az MLflow felhasználói felület Futtatás lapján.
• Ügynökértékelés felhasználói felületének: A Mosaic AI Ügynökértékelésben az egyes ügynökvégrehajtások nyomait a kiértékelési eredményben a Részletes nyomkövetési nézet megtekintése elemre kattintva tekintheti át.
• Trace Search API: A nyomkövetések programozott lekéréséhez használja a Trace Search API.

Ügynökök kiértékelése nyomkövetésekkel

A nyomkövetési adatok értékes erőforrásként szolgálnak az ügynökök kiértékeléséhez. A modellek végrehajtásával kapcsolatos részletes információk rögzítésével az MLflow Tracing az offline értékelésben is fontos szerepet játszott. A nyomkövetési adatokkal kiértékelheti az ügynök teljesítményét egy arany adatkészleten, azonosíthatja a problémákat, és javíthatja az ügynök teljesítményét.

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

Az ügynökértékeléssel kapcsolatos további információkért lásd: Kiértékelés futtatása és az eredmények megtekintése.

Üzembe helyezett ügynökök figyelése következtetési táblákkal

Miután üzembe helyez egy ügynököt a Mozaik AI-modellkiszolgálóban, a(z) következtetési táblákat használhatja az ügynök figyeléséhez. A következtetési táblák részletes naplókat tartalmaznak a kérésekről, válaszokról, ügynök nyomkövetésekről és a felülvizsgálati alkalmazás ügynöki visszajelzéséről. Ez az információ lehetővé teszi a hibák hibakeresését, a teljesítmény monitorozását és egy arany adatkészlet létrehozását offline kiértékeléshez.

Az ügynökök telepítéséhez szükséges következtetési táblák engedélyezéséhez további információkat találhat a Következtetési táblák engedélyezése az AI-ügynökökcímű témakörben.

Online nyomkövetések lekérdezése

Jegyzetfüzet használatával lekérdezheti a következtetési táblát, és elemezheti az eredményeket.

A nyomkövetések megjelenítéséhez futtassa display(<the request logs table>), és jelölje ki a megvizsgálandó sorokat:

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

Ügynökök figyelése

Lásd meg, hogyan figyelheti generatív AI alkalmazását.

Nyomkövetési többletterhelés késése

A nyomkövetések aszinkron módon vannak megírva a teljesítményre gyakorolt hatás minimalizálása érdekében. A nyomkövetés azonban továbbra is késést ad a végpont válaszsebességéhez, különösen akkor, ha az egyes következtetési kérelmek nyomkövetési mérete nagy. Databricks azt javasolja, hogy tesztelje a végpontját, hogy megértse a nyomkövetés késleltetési hatásait, mielőtt éles környezetbe telepítené.

Az alábbi táblázat hozzávetőleges becslést nyújt a késés nyomkövetési méret szerinti hatására:

Hibaelhárítás

Hibaelhárítással kapcsolatos információkért és gyakori kérdésekért tekintse meg az MLflow dokumentációt: Nyomonkövetési útmutató és a MLflow dokumentációt: Gyakori kérdések.