Teilen über

Erstellen eines KI-Agents und Bereitstellen auf Databricks-Apps

Erstellen Sie einen KI-Agent, und stellen Sie ihn mithilfe von Databricks-Apps bereit. Databricks Apps bietet Ihnen die vollständige Kontrolle über den Agentcode, die Serverkonfiguration und den Bereitstellungsworkflow. Dieser Ansatz ist ideal, wenn Sie benutzerdefiniertes Serververhalten, gitbasierte Versionsverwaltung oder lokale IDE-Entwicklung benötigen.

Vorschau der Agentchat-Benutzeroberfläche

Anforderungen

Aktivieren Sie Databricks-Apps in Ihrem Arbeitsbereich. Weitere Informationen finden Sie unter Einrichten ihres Databricks-Apps-Arbeitsbereichs und ihrer Entwicklungsumgebung.

Schritt 1. Klonen der Agent-App-Vorlage

Beginnen Sie, indem Sie eine vorgefertigte Agent-Vorlage aus dem Databricks-App-Vorlagen-Repository verwenden.

In diesem Lernprogramm wird die agent-openai-agents-sdk Vorlage verwendet, die Folgendes umfasst:

  • Ein Agent, der mit dem OpenAI Agent SDK erstellt wurde
  • Startcode für eine Agenten-Anwendung mit einer Konversations-REST-API und einer interaktiven Chat-Benutzeroberfläche
  • Code zum Auswerten des Agents mithilfe von MLflow

Wählen Sie einen der folgenden Pfade aus, um die Vorlage einzurichten:

Benutzeroberfläche des Arbeitsbereichs

Installieren Sie die App-Vorlage mithilfe der Arbeitsbereichs-Benutzeroberfläche. Dadurch wird die App installiert und auf einer Rechenressource in Ihrem Arbeitsbereich bereitgestellt. Anschließend können Sie die Anwendungsdateien zur Weiteren Entwicklung mit Ihrer lokalen Umgebung synchronisieren.

  1. Klicken Sie in Ihrem Databricks-Arbeitsbereich auf +Neue>App.

  2. Klicken Sie auf Agents Agent>– OpenAI Agents SDK.

  3. Erstellen Sie ein neues MLflow-Experiment mit dem Namen openai-agents-template , und schließen Sie den Rest der Einrichtung ab, um die Vorlage zu installieren.

  4. Nachdem Sie die App erstellt haben, klicken Sie auf die App-URL, um die Chat-UI zu öffnen.

Nachdem Sie die App erstellt haben, laden Sie den Quellcode auf Ihren lokalen Computer herunter, um sie anzupassen:

  1. Kopieren des ersten Befehls unter "Dateien synchronisieren"

    Dateien für Databricks-Apps synchronisieren

  2. Führen Sie in einem lokalen Terminal den kopierten Befehl aus.

Klonen von GitHub

Um in einer lokalen Umgebung zu starten, klonen Sie das Agentenvorlagen-Repository und öffnen Sie das -Verzeichnis:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Schritt 2. Grundlegendes zur Agentanwendung

Die Agentvorlage veranschaulicht eine produktionsfähige Architektur mit diesen Schlüsselkomponenten. Öffnen Sie die folgenden Abschnitte, um weitere Details zu den einzelnen Komponenten zu erhalten:

Einfaches Diagramm

Öffnen Sie die folgenden Abschnitte, um weitere Details zu den einzelnen Komponenten zu erhalten:

MLflow AgentServer

Ein asynchroner FastAPI-Server, der Agentanforderungen mit integrierter Ablaufverfolgung und Observierbarkeit verarbeitet. Der AgentServer stellt den /invocations Endpunkt zum Abfragen Ihres Agents bereit und verwaltet automatisch das Anforderungsrouting, die Protokollierung und die Fehlerbehandlung.

ResponsesAgent Schnittstelle

Databricks empfiehlt MLflow ResponsesAgent zum Erstellen von Agents. ResponsesAgent Ermöglicht Es Ihnen, Agents mit jedem Drittanbieterframework zu erstellen und sie dann mit Databricks AI-Features für robuste Protokollierung, Ablaufverfolgung, Auswertung, Bereitstellung und Überwachung zu integrieren.

ResponsesAgent integriert problemlos bereits existierende Agents für die Databricks-Kompatibilität.

Informationen zum Erstellen einer ResponsesAgentDatei finden Sie in den Beispielen in der MLflow-Dokumentation – ResponsesAgent for Model Serving.

ResponsesAgent bietet die folgenden Vorteile:

  • Erweiterte Agent-Funktionen

    • Multi-Agent-Unterstützung
    • Streamingausgabe: Streamen Sie die Ausgabe in kleineren Blöcken.
    • Umfassender Nachrichtenverlauf bei Toolaufrufen: Rückgabe mehrerer Nachrichten, einschließlich zwischengeschalteter Nachrichten, für eine verbesserte Qualität und Konversationsverwaltung.
    • Unterstützung bei der Bestätigung von Toolaufrufen
    • Unterstützung von langfristigen Tools

  • Vereinfachte Entwicklung, Bereitstellung und Überwachung

    • Erstellen Sie Agenten mit jedem beliebigen Framework: Verpacken Sie jeden bestehenden Agenten mithilfe der ResponsesAgent Schnittstelle, um eine sofortige Kompatibilität mit AI Playground, Agent Evaluation und Agent Monitoring zu erreichen.
    • Typisierte Erstellungsschnittstellen: Schreiben Sie Agent-Code mit typisierten Python-Klassen, und nutzen Sie dabei das AutoVervollständigen von IDE und Notebook.
    • Automatische Ablaufverfolgung: MLflow verfolgt Ihre predict und predict_stream Funktionen automatisch und aggregiert gestreamte Antworten, um die Auswertung und Anzeige zu erleichtern.
    • Kompatibel mit dem OpenAI-SchemaResponses: Siehe OpenAI: Antworten vs. ChatCompletion.
OpenAI Agents SDK

Die Vorlage verwendet das OpenAI Agents SDK als Agent-Framework für Konversationsverwaltung und Tool-Koordination. Sie können Agents mithilfe eines beliebigen Frameworks erstellen. Der Schlüssel liegt darin, Ihren Agenten mit der MLflow-Schnittstelle ResponsesAgent zu umwickeln.

MCP-Server (Model Context Protocol)

Die Vorlage stellt eine Verbindung mit Databricks MCP-Servern bereit, um Agents Zugriff auf Tools und Datenquellen zu gewähren. Siehe Model Context Protocol (MCP) für Databricks.

Autorenerstellungsagenten mit KI-Programmiierungsassistenten

Databricks empfiehlt die Verwendung von KI-Codierungsassistenten wie Claude, Cursor und Copilot, um Agenten zu erstellen. Verwenden Sie die bereitgestellten Agent-Fähigkeiten in /.claude/skills, und die AGENTS.md Datei, um KI-Assistenten dabei zu helfen, die Projektstruktur, die verfügbaren Tools und bewährten Methoden zu verstehen. Agents können diese Dateien automatisch lesen, um die Databricks-Apps zu entwickeln und bereitzustellen.

Themen zur erweiterten Inhaltserstellung

Streaming-Antworten

Streaming-Antworten

Streaming ermöglicht Es Agents, Antworten in Echtzeitblöcken zu senden, anstatt auf die vollständige Antwort zu warten. Um Streaming mit ResponsesAgentzu implementieren, geben Sie eine Reihe von Delta-Ereignissen aus, gefolgt von einem endgültigen Abschlussereignis:

  1. Übertragen von Delta-Ereignissen: Senden Sie mehrere output_text.delta Ereignisse mit demselben item_id, um Textblöcke in Echtzeit zu streamen.
  2. Fertig stellen: Senden Sie ein endgültiges response.output_item.done Ereignis mit demselben item_id wie die Delta-Ereignisse, die den vollständigen endgültigen Ausgabetext enthalten.

Jedes Delta-Ereignis streamt einen Textabschnitt an den Client. Das letzte fertige Ereignis enthält den vollständigen Antworttext und signalisiert Databricks folgendes:

  • Verfolgen Sie die Ergebnisse Ihres Agents mit der MLflow-Ablaufverfolgung
  • Aggregierte gestreamte Antworten in KI-Gateway-Ableitungstabellen
  • Zeige die vollständige Ausgabe in der AI Playground-Oberfläche an

Streamingfehlerverteilung

Mosaic AI propagiert alle Fehler, die beim Streaming mit dem letzten Token unter databricks_output.error auftreten. Es liegt bei dem aufrufenden Client, diesen Fehler ordnungsgemäß zu behandeln und anzuzeigen.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}
Benutzerdefinierte Eingaben und Ausgaben

Benutzerdefinierte Eingaben und Ausgaben

Einige Szenarien erfordern möglicherweise zusätzliche Eingaben von Agenten, wie z. B. client_type und session_id, oder Ausgaben wie Abrufquellenlinks, die nicht in den Chatverlauf für zukünftige Interaktionen einbezogen werden sollten.

Für diese Szenarien unterstützt MLflow ResponsesAgent die Felder custom_inputs und custom_outputsnativ. Sie können in den oben aufgeführten Frameworkbeispielen über request.custom_inputs auf die benutzerdefinierten Eingaben zugreifen.

Die Agent Evaluation Review-App unterstützt das Rendern von Ablaufverfolgungen für Agenten mit zusätzlichen Eingabefeldern nicht.

Bereitstellen custom_inputs in der AI-Playground- und Überprüfungs-App

Wenn Ihr Agent zusätzliche Eingaben mithilfe des custom_inputs Felds akzeptiert, können Sie diese Eingaben sowohl im AI-Playground als auch in der Rezensions-App manuell bereitstellen.

  1. Wählen Sie in der AI Playground- oder in der Agent Review-App das Zahnradsymbol Zahnrad-Symbol aus.

  2. Aktivieren Sie custom_inputs.

  3. Stellen Sie ein JSON-Objekt bereit, das dem definierten Eingabeschema Ihres Agents entspricht.

    Stellen Sie benutzerdefinierte_Eingaben im KI-Spielplatz bereit.

Benutzerdefinierte Retriever-Schemas

Benutzerdefinierte Retriever-Schemas

KI-Agents verwenden häufig Retriever, um unstrukturierte Daten aus Vektorsuchindizes zu finden und abzufragen. Beispiele für Retriever-Tools finden Sie unter Verbinden von Agents mit unstrukturierten Daten.

Verfolgen Sie diese Retriever in Ihrem Agent mit MLflow RETRIEVER, um Databricks-Produktfeatures zu aktivieren, einschließlich:

  • Automatisches Anzeigen von Links zu abgerufenen Quelldokumenten in der AI Playground-Benutzeroberfläche
  • Automatisierte Ausführung der Abrufübereinstimmung und der Relevanzbewertung in der Agentenbewertung

Anmerkung

Databricks empfiehlt die Verwendung von Retriever-Tools, die von Databricks AI Bridge-Paketen wie databricks_langchain.VectorSearchRetrieverTool und databricks_openai.VectorSearchRetrieverTool bereitgestellt werden, da sie bereits dem MLflow-Retriever-Schema entsprechen. Weitere Informationen finden Sie unter Lokale Entwicklung von Abrufertools für die Vektorsuche mit AI Bridge.

Wenn Ihr Agent Retriever-Spans mit einem benutzerdefinierten Schema enthält, rufen Sie mlflow.models.set_retriever_schema auf, wenn Sie Ihren Agenten im Code definieren. Dadurch werden die Ausgabespalten des Retrievers den erwarteten Feldern von MLflow (primary_key, text_column, doc_uri) zugeordnet.

import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)

Anmerkung

Die doc_uri Spalte ist besonders wichtig beim Auswerten der Leistung des Retrievers. doc_uri ist der Hauptbezeichner für Dokumente, die vom Abrufer zurückgegeben werden. Damit können Sie sie mit Auswertungssätzen für die Grundwahrheit vergleichen. Siehe Auswertungssätze (MLflow 2)

Schritt 3. Lokales Ausführen der Agent-App

Richten Sie Ihre lokale Umgebung ein:

  1. Installiere uv (Python-Paket-Manager), nvm (Node-Version-Manager) und Databricks CLI:

  2. Wechseln Sie in das agent-openai-agents-sdk Verzeichnis.

  3. Führen Sie die bereitgestellten Schnellstartskripts aus, um Abhängigkeiten zu installieren, Ihre Umgebung einzurichten und die App zu starten.

    uv run quickstart
uv run start-app

Öffnen Sie in einem Browser die Seite http://localhost:8000, um das Chatten mit dem Agenten zu starten.

Schritt 4. Konfigurieren der Authentifizierung

Ihr Agent benötigt eine Authentifizierung für den Zugriff auf Databricks-Ressourcen. Databricks-Apps bieten zwei Authentifizierungsmethoden:

App-Autorisierung (Standard)

Die App-Autorisierung verwendet einen Dienstprinzipal, den Azure Databricks automatisch für Ihre App erstellt. Alle Benutzer haben dieselben Berechtigungen.

Erteilen von Berechtigungen für das MLflow-Experiment:

  1. Klicken Sie auf der Startseite Ihrer App auf "Bearbeiten ".
  2. Navigieren Sie zum Schritt "Konfigurieren" .
  3. Fügen Sie im Abschnitt "App-Ressourcen " die MLflow-Experimentressource mit Can Edit Berechtigungen hinzu.

Fügen Sie für andere Ressourcen (Vektorsuche, Genie-Bereiche, bereitgestellte Endpunkte) auf die gleiche Weise im Abschnitt App-Ressourcen hinzu.

Weitere Informationen finden Sie unter "App-Autorisierung ".

Benutzerautorisierung

Mit der Benutzerautorisierung kann Ihr Agent mit den individuellen Berechtigungen jedes Benutzers handeln. Verwenden Sie diese Vorgehensweise, wenn Sie die Zugriffssteuerung oder Überwachungspfade pro Benutzer benötigen.

Fügen Sie ihrem Agent diesen Code hinzu:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside predict or predict_stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Wichtig: Initialisieren Sie get_user_workspace_client() innerhalb Ihrer predict Funktionen, predict_stream nicht während des App-Starts. Benutzeranmeldeinformationen sind nur bei der Verarbeitung einer Anforderung vorhanden.

Konfigurieren von Bereichen: Fügen Sie autorisierungsbereiche in der Benutzeroberfläche von Databricks Apps hinzu, um zu definieren, auf welche APIs Ihr Agent im Auftrag von Benutzern zugreifen kann.

Eine vollständige Einrichtungsanleitung finden Sie unter Benutzerautorisierung .

Schritt 5. Den Agenten auswerten

Die Vorlage enthält Agentenbewertungscode. Weitere Informationen finden Sie unter agent_server/evaluate_agent.py. Bewerten Sie die Relevanz und Sicherheit der Antworten Ihres Agenten, indem Sie Folgendes in einem Terminal ausführen:

uv run agent-evaluate

Schritt 6. Bereitstellen des Agents für Databricks-Apps

Stellen Sie nach der Konfiguration der Authentifizierung Ihren Agent für Databricks bereit. Stellen Sie sicher, dass die Databricks CLI installiert und konfiguriert ist.

  1. Wenn Sie das Repository lokal geklont haben, erstellen Sie die Databricks-App, bevor Sie es bereitstellen. Wenn Sie Ihre App über die Arbeitsbereichs-UI erstellt haben, überspringen Sie diesen Schritt, da die App und das MLflow-Experiment bereits konfiguriert sind.

    databricks apps create agent-openai-agents-sdk

  2. Synchronisieren Sie lokale Dateien mit Ihrem Arbeitsbereich. Siehe Bereitstellen der App.

    DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
databricks sync . "/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk"

  3. Stellen Sie Ihre Databricks-App bereit.

    databricks apps deploy agent-openai-agents-sdk --source-code-path /Workspace/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk

Synchronisieren und stellen Sie Ihren Agent für zukünftige Updates erneut bereit.

Schritt 7. Bereitgestellten Agent abfragen

Benutzer fragen Ihren bereitgestellten Agent mithilfe von OAuth-Token ab. Persönliche Zugriffstoken (PATs) werden für Databricks-Apps nicht unterstützt.

Generieren Sie ein OAuth-Token mithilfe der Databricks CLI:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Verwenden Sie das Token, um den Agent abzufragen:

curl -X POST <app-url.databricksapps.com>/invocations \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Einschränkungen

Es werden nur mittlere und große Computegrößen unterstützt. Siehe Konfigurieren der Computegröße für eine Databricks-App.

  • Last updated on