Sammeln von Feedback und Erwartungen durch Kennzeichnen vorhandener Spuren

Eine der effektivsten Methoden, um Ihre GenAI-Anwendung zu verbessern, besteht darin, dass Fachexperten bestehende Abläufe überprüfen und kennzeichnen. Die Prüf-App von MLflow bietet einen strukturierten Prozess zum Sammeln dieses Expertenfeedbacks zu echten Interaktionen mit Ihrer Anwendung.

Wann vorhandene Traces gekennzeichnet werden sollten

Bitten Sie Experten, vorhandene Interaktionen mit Ihrer App zu überprüfen, um Feedback und Erwartungen zu liefern.

Gehen Sie folgendermaßen vor:

• Verstehen, wie qualitativ hochwertige, korrekte Antworten für bestimmte Abfragen aussehen
• Eingaben sammeln, um LLM-Modelle an Ihre geschäftlichen Anforderungen anzupassen
• Erstellen von Auswertungsdatensätzen aus Produktionsablaufverfolgungen

Identifizieren von Spuren zur Überprüfung durch Experten

Identifizieren Sie vor dem Erstellen einer Labeling-Sitzung Ablaufverfolgungen, die von einer Expertenüberprüfung profitieren würden. Konzentrieren Sie sich auf Fälle, die ein menschliches Urteil erfordern:

• Spuren mit mehrdeutiger oder grenzwertiger Qualität
• Edge-Fälle, die nicht von automatisierten Richtern abgedeckt werden
• Beispiele, in denen automatisierte Metriken mit der erwarteten Qualität nicht übereinstimmen
• Repräsentative Beispiele verschiedener Benutzerinteraktionsmuster

Sie können Protokolle in der MLflow-Benutzeroberfläche nach Status, Tags oder Zeitbereich filtern. Informationen zur programmgesteuerten Auswahl mit erweiterten Filtern finden Sie unter Abfrageablaufverfolgungen über DAS SDK.

Voraussetzungen

• MLflow und erforderliche Pakete müssen installiert werden. Die in diesem Handbuch beschriebenen Features erfordern MLflow Version 3.1.0 oder höher. Führen Sie den folgenden Befehl aus, um das MLflow SDK zu installieren oder zu aktualisieren, einschließlich der für die Databricks-Integration erforderlichen Extras:

  pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"
  

• Ihre Entwicklungsumgebung muss mit dem MLflow Experiment verbunden sein, in dem Ihre GenAI-Anwendungsablaufverfolgungen protokolliert werden.

  • Folgen Sie dem Lernprogramm: Verbinden Sie Ihre Entwicklungsumgebung mit MLflow , um Ihre Entwicklungsumgebung zu verbinden.

• Domänenexperten benötigen die folgenden Berechtigungen, um die Review-App zum Labeln vorhandener Ablaufverfolgungen zu verwenden.

  • Kontozugriff: Muss in Ihrem Databricks-Konto bereitgestellt werden, aber keinen Zugriff auf Ihren Arbeitsbereich benötigen.

    Für Benutzer ohne Arbeitsbereichszugriff können Kontoadministratoren:

    • Verwenden Sie die SCIM-Bereitstellung auf Kontoebene, um Benutzer von Ihrem Identitätsanbieter synchronisieren.
    • Manuelles Registrieren von Benutzern und Gruppen in Databricks

    Details finden Sie unter Benutzer- und Gruppenverwaltung .

  • Experimentzugriff: CAN_EDIT Berechtigung für das MLflow-Experiment.

Schritt 1: Erstellen einer App mit Tracing

Bevor Sie Feedback sammeln können, müssen Sie Spuren von Ihrer GenAI-Anwendung protokollieren lassen. Diese Ablaufverfolgungen erfassen die Eingaben, Ausgaben und Zwischenschritte der Ausführung Ihrer Anwendung, einschließlich aller Toolaufrufe oder Retriever-Aktionen.

Nachfolgend finden Sie ein Beispiel, wie Sie Traces aufzeichnen können. Dieses Beispiel enthält einen gefälschten Retriever, damit wir veranschaulichen können, wie die abgerufenen Dokumente in den Spuren in der Überprüfung App gerendert werden. Weitere Informationen darüber, wie die Review App Spuren rendert, finden Sie unter App-Inhaltsrendering.

1. Initialisieren Sie einen OpenAI-Client, um eine Verbindung mit von Databricks gehosteten LLMs oder LLMs herzustellen, die von OpenAI gehostet werden.

   Von Databricks gehostete LLMs

   Verwenden Sie databricks-openai, um einen OpenAI-Client zu erhalten, der eine Verbindung zu von Databricks gehosteten LLMs herstellt. Wählen Sie ein Modell aus den verfügbaren Foundation-Modellen aus.

   import mlflow
   from databricks_openai import DatabricksOpenAI
   
   # Enable MLflow's autologging to instrument your application with Tracing
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client that is connected to Databricks-hosted LLMs
   client = DatabricksOpenAI()
   
   # Select an LLM
   model_name = "databricks-claude-sonnet-4"
   

   OpenAI-gehostete LLMs

   Verwenden Sie das native OpenAI SDK, um eine Verbindung mit in OpenAI gehosteten Modellen herzustellen. Wählen Sie ein Modell aus den verfügbaren OpenAI-Modellen aus.

   import mlflow
   import os
   import openai
   
   # Ensure your OPENAI_API_KEY is set in your environment
   # os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured
   
   # Enable auto-tracing for OpenAI
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client connected to OpenAI SDKs
   client = openai.OpenAI()
   
   # Select an LLM
   model_name = "gpt-4o-mini"
   

2. Definieren Sie Ihre Anwendung:

   from mlflow.entities import Document
   from typing import List, Dict
   
   
   # Spans of type RETRIEVER are rendered in the Review App as documents.
   @mlflow.trace(span_type="RETRIEVER")
   def retrieve_docs(query: str) -> List[Document]:
    normalized_query = query.lower()
    if "john doe" in normalized_query:
        return [
            Document(
                id="conversation_123",
                page_content="John Doe mentioned issues with login on July 10th. Expressed interest in feature X.",
                metadata={"doc_uri": "http://domain.com/conversations/123"},
            ),
            Document(
                id="conversation_124",
                page_content="Follow-up call with John Doe on July 12th. Login issue resolved. Discussed pricing for feature X.",
                metadata={"doc_uri": "http://domain.com/conversations/124"},
            ),
        ]
    else:
        return [
            Document(
                id="ticket_987",
                page_content="Acme Corp raised a critical P0 bug regarding their main dashboard on July 15th.",
                metadata={"doc_uri": "http://domain.com/tickets/987"},
            )
        ]
   
   # Sample app to review traces from
   @mlflow.trace
   def my_app(messages: List[Dict[str, str]]):
    # 1. Retrieve conversations based on the last user message
    last_user_message_content = messages[-1]["content"]
    retrieved_documents = retrieve_docs(query=last_user_message_content)
    retrieved_docs_text = "\n".join([doc.page_content for doc in retrieved_documents])
   
    # 2. Prepare messages for the LLM
    messages_for_llm = [
        {"role": "system", "content": "You are a helpful assistant!"},
        {
            "role": "user",
            "content": f"Additional retrieved context:\n{retrieved_docs_text}\n\nNow, please provide the one-paragraph summary based on the user's request {last_user_message_content} and this retrieved context.",
        },
    ]
   
    # 3. Call LLM to generate the summary
    return client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted claude-sonnet-4-5. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=messages_for_llm,
    )
   

Schritt 2: Definieren von Bezeichnungsschemas

Kennzeichnungsschemata definieren die Fragen und Eingabetypen, die von Domänenexperten verwendet werden, um Feedback zu Ihren Traces bereitzustellen. Sie können die integrierten Schemas von MLflow verwenden oder benutzerdefinierte Schemas erstellen, die auf Ihre spezifischen Bewertungskriterien zugeschnitten sind.

Es gibt zwei Haupttypen von Bezeichnungsschemas:

• Erwartungstyp (type="expectation"): Wird verwendet, wenn der Experte eine "Bodenwahrheit" oder eine richtige Antwort liefert. Zum Beispiel, indem Sie die expected_facts für die Antwort eines RAG-Systems. Diese Bezeichnungen können häufig direkt in Auswertungsdatensätzen verwendet werden.
• Feedbacktyp (type="feedback"): Wird für subjektive Einschätzungen, Bewertungen oder Klassifizierungen verwendet. Bewerten Sie beispielsweise eine Antwort auf einer Skala von 1 bis 5 hinsichtlich Höflichkeit oder um zu klassifizieren, ob eine Antwort bestimmte Kriterien erfüllt.

Um die verschiedenen Eingabemethoden für Ihre Schemas, wie z. B. kategorische Optionen (Radiobuttons), numerische Skalen oder Freiformtext, zu verstehen, sehen Sie sich "Erstellen und Verwalten von Labelingschemas" an.

from mlflow.genai.label_schemas import create_label_schema, InputCategorical, InputText

# Collect feedback on the summary
summary_quality = create_label_schema(
    name="summary_quality",
    type="feedback",
    title="Is this summary concise and helpful?",
    input=InputCategorical(options=["Yes", "No"]),
    instruction="Please provide a rationale below.",
    enable_comment=True,
    overwrite=True,
)

# Collect a ground truth summary
expected_summary = create_label_schema(
    name="expected_summary",
    type="expectation",
    title="Please provide the correct summary for the user's request.",
    input=InputText(),
    overwrite=True,
)

Schritt 3: Erstellen einer Labeling-Sitzung

Eine Bezeichnungssitzung ist eine spezielle Art von MLflow-Run, die eine Reihe von Ablaufverfolgungen organisiert, die von bestimmten Experten mithilfe ausgewählter Etikettierungsschemas überprüft werden. Sie fungiert als Warteschlange für den Überprüfungsprozess.

Weitere Informationen finden Sie unter Erstellen und Verwalten von Beschriftungssitzungen.

Hier erfahren Sie, wie Sie eine Etikettierungssitzung erstellen:

from mlflow.genai.labeling import create_labeling_session

# Create the labeling session with the schemas we created in the previous step
label_summaries = create_labeling_session(
    name="label_summaries",
    assigned_users=[],
    label_schemas=[summary_quality.name, expected_summary.name],
)

Schritt 4: Generieren von Traces und Hinzufügen zur Labeling-Sitzung

Sobald Ihre Bezeichnung erstellt ist, müssen Sie ihr Spuren hinzufügen. Die Spuren werden in die Beschriftungssitzung kopiert, so dass Bezeichnungen oder Änderungen, die während des Überprüfungsprozesses vorgenommen werden, keine Auswirkungen auf die ursprünglich protokollierten Spuren haben.

Sie können in Ihrem MLflow-Experiment jede beliebige Spur hinzufügen. Weitere Informationen finden Sie unter Erstellen und Verwalten von Beschriftungssitzungen.

import mlflow

# Use verison tracking to be able to easily query for the traces
tracked_model = mlflow.set_active_model(name="my_app")

# Run the app to generate traces
sample_messages_1 = [
    {"role": "user", "content": "what issues does john doe have?"},
]
summary1_output = my_app(sample_messages_1)

sample_messages_2 = [
    {"role": "user", "content": "what issues does acme corp have?"},
]
summary2_output = my_app(sample_messages_2)

# Query for the traces we just generated
traces = mlflow.search_traces(model_id=tracked_model.model_id)

# Add the traces to the session
label_summaries.add_traces(traces)

# Print the URL to share with your domain experts
print(f"Share this Review App with your team: {label_summaries.url}")

Schritt 5: Teilen Sie die Review-App mit Experten

Nachdem Ihre Bezeichnungssitzung mit Spuren gefüllt ist, können Sie die URL mit Ihren Domänenexperten teilen. Über diese URL können sie auf die Überprüfung App zugreifen, die ihnen zugewiesenen Spuren anzeigen (oder aus nicht zugewiesenen Spuren auswählen) und anhand der von Ihnen konfigurierten Bezeichnungsschemata Feedback geben.

Anpassen der Benutzeroberfläche der Überprüfungs-App (optional)

Für Anwendungsfälle, die eine benutzerdefinierte Ablaufverfolgungsvisualisierung, maßgeschneiderte Bezeichnungsschnittstellen oder bestimmte Workflows erfordern, stellen Sie eine anpassbare Prüf-App-Vorlage bereit. Diese Open-Source-Vorlage verwendet dieselben MLflow-Back-End-APIs und dasselbe Datenmodell (Labeling-Sitzungen, Schemas und Bewertungen), während Sie die vollständige Kontrolle über die Frontend-Erfahrung erhalten. Zu den Anpassungsoptionen gehören:

• Spezialisierte Trace-Renderer für Ihre Agententypen
• Benutzerdefinierte Beschriftungsoberflächenlayouts und -interaktionen
• Domänenspezifische Visualisierungen
• Steuern, welche Protokollierungsinformationen für Prüfer angezeigt werden

Das Vorlagen-Repository enthält Befehlszeilentools für die programmgesteuerte Einrichtung oder einen KI-Assistenten (Claude Code) zur interaktiven Anpassung: GitHub - custom-mlflow-review-app. Die angepasste Review-App wird als Databricks-App bereitgestellt und direkt mit Ihren vorhandenen MLflow-Experimenten und Beschriftungssitzungen integriert. Eine vollständige Anpassungs- und Bereitstellungsanleitung finden Sie in der Dokumentation zum Vorlagen-Repository.

Schritt 6: Anzeigen und Verwenden gesammelter Bezeichnungen

Nachdem Ihre Domänenexperten ihre Überprüfungen abgeschlossen haben, wird das gesammelte Feedback im Rahmen der Beschriftungssitzung an die Spuren angehängt. Sie können diese Bezeichnungen programmgesteuert abrufen, um sie zu analysieren oder sie zum Erstellen von Auswertungsdatensätzen zu verwenden.

Etiketten werden als Assessment-Objekte auf jedem Trace innerhalb der Beschriftungssitzung gespeichert.

Verwenden Sie die MLflow-UI

Um die Ergebnisse zu überprüfen, navigieren Sie zum MLflow-Experiment.

Verwenden des MLflow SDK

Der folgende Code holt alle Spuren aus der Ausführung der Kennzeichnungssitzung und extrahiert die Bewertungen (Bezeichnungen) in ein Pandas DataFrame zur einfacheren Analyse.

labeled_traces_df = mlflow.search_traces(run_id=label_summaries.mlflow_run_id)

Überprüfen des Renderns von App-Inhalten

Beim Bezeichnen vorhandener Spuren verwendet die Review-App die Eingaben und Ausgaben aus vorhandenen Spuren und speichert die Ergebnisse in MLflow-Traces innerhalb einer Bezeichnungssitzung. Sie müssen ein benutzerdefiniertes Bezeichnungsschema bereitstellen, um die benutzerdefinierten Fragen und Kriterien für Ihren Anwendungsfall zu definieren.

Die Überprüfungs-App rendert automatisch unterschiedliche Inhaltstypen aus Ihrer MLflow-Ablaufverfolgung:

• Abgerufene Dokumente: Dokumente innerhalb eines RETRIEVER Bereichs werden zur Anzeige gerendert.
• OpenAI-Formatnachrichten: Eingaben und Ausgaben der MLflow Trace nach OpenAI-Chatunterhaltungen werden gerendert:
  • outputs enthalten ein ChatCompletions-Objekt im OpenAI-Format
  • inputsoder outputs Diktaten, die einen messages Schlüssel mit einem Array von OpenAI-Format-Chatnachrichten enthalten
    • Wenn das messages Array OpenAI Format-Toolaufrufe enthält, werden diese ebenfalls gerendert.
• Wörterbücher: Eingaben und Ausgaben der MLflow-Ablaufverfolgung, die Dictionaries sind, werden als anschaulich formatierte JSONs gerendert.

Andernfalls werden der Inhalt von input und output aus der Root-Spanne jeder Ablaufverfolgung als primärer Inhalt für die Überprüfung verwendet.

Beispiel-Notebook

Das folgende Notizbuch enthält den gesamten Code auf dieser Seite.

Feedback von Fachexperten im Notizbuch sammeln

Notebook abrufen

Nächste Schritte

Umwandeln in Evaluierungsdatensätze

Bezeichnungen vom Typ "Erwartung" (z. B. aus expected_summary unserem Beispiel) eignen sich besonders zum Erstellen von Auswertungsdatensätzen. Diese Datensätze können dann mit mlflow.genai.evaluate() um systematisch neue Versionen Ihrer GenAI-Anwendung anhand von durch Experten definierten Grunddaten zu testen.