Freigeben über

Bereitstellen eines Agents für generative KI-Anwendung

  • Artikel

Wichtig

Dieses Feature befindet sich in der Public Preview.

In diesem Artikel wird gezeigt, wie Sie Ihren KI-Agent mithilfe der deploy() Funktion aus der Agent Framework Python-API bereitstellen.

Anforderungen

  • MLflow 2.13.1 oder höher zum Bereitstellen von Agents mithilfe der deploy() API von databricks.agents.

  • Registrieren Sie einen KI-Agenten in Unity Catalog. Siehe Registrieren Sie den Agenten im Unity-Katalog.

  • Für die Bereitstellung von Agents von außerhalb eines Databricks-Notizbuchs ist databricks-agents SDK-Version 0.12.0 oder höher erforderlich.

  • Installieren des databricks-agents-SDK.

    %pip install databricks-agents
dbutils.library.restartPython()

Bereitstellen eines Agents mithilfe von deploy()

Die Deploy() -Funktion führt folgende Aktionen aus:

  • Erstellt ein CPU-Modell, das Endpunkte für Ihren Agent bedient, die in Ihre benutzerorientierte Anwendung integriert werden können.

    • Um die Kosten für Leerlaufendpunkte (auf Kosten einer erhöhten Zeit für die Bereitstellung anfänglicher Abfragen) zu reduzieren, können Sie die Skalierung auf Null für Ihren Dienstendpunkt aktivieren, indem Sie an scale_to_zero_enabled=Truedie Bereitstellungsendpunkte übergebendeploy(). Siehe Endpunktskalierungserwartungen.
    • Ermöglicht Rückschlusstabellen mit AI Gateway auf dem Modell, das den Endpunkt bedient. Weitere Informationen finden Sie unter Überwachung der mit dem AI Gateway versehenen Rückschlusstabellen.

    Hinweis

    Bei Streamingantwortprotokollen werden nur ChatCompletion-kompatible Felder und Ablaufverfolgungen aggregiert.

  • Aktiviert die Überprüfungs-App für Ihren Agent Mit der Rezensions-App können Projektbeteiligte mit dem Agent chatten und Feedback über die Benutzeroberfläche der Rezensions-App abgeben.

  • Protokolliert alle Anforderungen an die Überprüfungs-App oder die REST-API in einer Rückschlusstabelle. Die protokollierten Daten umfassen Abfrageanforderungen, Antworten und Zwischenablaufverfolgungsdaten aus der MLflow-Ablaufverfolgung.

  • Erstellt ein Feedbackmodell mit demselben Katalog und Schema wie der Agent, den Sie bereitstellen möchten. Dieses Feedbackmodell ist der Mechanismus, mit dem Feedback aus der Rezensions-App übernommen und in einer Rückschlusstabelle protokolliert werden kann. Dieses Modell wird am gleichen CPU-Model Serving-Endpunkt bereitgestellt wie Ihr bereitgestellter Agent. Da an diesem Dienstendpunkt Rückschlusstabellen aktiviert sind, ist es möglich, Feedback aus der Rezensions-App in einer Rückschlusstabelle zu protokollieren.

Hinweis

Bereitstellungsvorgänge können bis zu 15 Minuten dauern. Unformatierte JSON-Nutzlasten dauern 10 bis 30 Minuten, und die formatierten Protokolle werden ungefähr jede Stunde aus den rohen Nutzlasten verarbeitet.


from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

Agent-erweiterte Rückschlusstabellen

Die deploy() erstellt drei Rückschlusstabellen für jede Bereitstellung, um Anforderungen und Antworten auf und vom Agent zu protokollieren, der endpunktend ist. Die Nutzer können davon ausgehen, dass die Daten innerhalb einer Stunde nach der Interaktion mit ihrem Einsatz in der Payload-Tabelle stehen.

Payload-Anforderungsprotokolle und Bewertungsprotokolle können länger aufgefüllt werden, werden aber letztendlich von der Roh-Payload-Tabelle abgeleitet. Sie können Anforderungs- und Bewertungsprotokolle aus der Payload-Tabelle selbst extrahieren. Löschungen und Aktualisierungen der Nutzlasttabelle werden nicht in den Payload-Anforderungsprotokollen oder den Payload-Bewertungsprotokollen widerzuspiegeln.

Hinweis

Wenn Sie die Azure Storage-Firewall aktiviert haben, wenden Sie sich an Ihr Databricks-Kontoteam, um Rückschlusstabellen für Ihre Endpunkte zu aktivieren.

Tabelle Beispiel Unity Catalog-Tabellenname Was ist in jeder Tabelle?
Payload {catalog_name}.{schema_name}.{model_name}_payload Rohe JSON-Anfrage- und Antwort-Payloads
Nutzlastanforderungsprotokolle {catalog_name}.{schema_name}.{model_name}_payload_request_logs Formatierte Anforderung und Antworten, MLflow-Ablaufverfolgungen
Nutzlastbewertungsprotokolle {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Formatiertes Feedback, wie in der Rezensions-App angegeben, für jede Anforderung

Das folgende Beispiel zeigt das Schema für die Anforderungsprotokolltabelle.

Spaltenname type Beschreibung
client_request_id String Clientanforderungs-ID, in der Regel null
databricks_request_id String Databricks-Anforderungs-ID
date Datum Anforderungsdatum
timestamp_ms Lang Zeitstempel in Millisekunden
timestamp Timestamp Zeitstempel der Anforderung
status_code Ganzzahl Statuscode des Endpunkts
execution_time_ms Lang Gesamtausführungszeit in Millisekunden
conversation_id String Die aus Anforderungsprotokollen extrahierte Unterhaltungs-ID
request String Die letzte Benutzerabfrage aus der Unterhaltung des Benutzers. Wird aus der RAG-Anforderung extrahiert.
response String Die Antwort, die dem Benutzer gegeben wurde. Wird aus der RAG-Anforderung extrahiert.
request_raw String Zeichenfolgendarstellung der Anforderung
response_raw String Zeichenfolgendarstellung der Antwort
trace String Zeichenfolgendarstellung der Ablaufverfolgung, die aus den databricks_options der Antwortstruktur extrahiert wurde
sampling_fraction Double Auswahlsatz
request_metadata Zuordnung[Zeichenfolge, Zeichenfolge] Eine Metadatenzuordnung im Zusammenhang mit dem Modellbereitstellungsendpunkt, der der Anforderung zugeordnet ist. Diese Zuordnung enthält den Namen des Endpunkts und des Modells sowie die Modellversion, die für Ihren Endpunkt verwendet wird.
schema_version String Ganze Zahl für die Schemaversion

Nachfolgend sehen Sie das Schema für Bewertungsprotokolltabelle.

Spaltenname type Beschreibung
request_id String Databricks-Anforderungs-ID
step_id String Von der Abrufbewertung abgeleitet
source Struktur Ein Strukturfeld, das angibt, wer die Bewertung erstellt hat
timestamp Timestamp Zeitstempel der Anforderung
text_assessment Struktur Ein Strukturfeld, das die Daten zu Feedback aus der Rezensions-App enthält, das zu den Antworten des Agents gegeben wurde
retrieval_assessment Struktur Ein Strukturfeld, das die Daten zu Feedback zu den Dokumenten enthält, die für eine Antwort abgerufen wurden

Authentifizierung für abhängige Ressourcen

KI-Agents müssen sich häufig bei anderen Ressourcen authentifizieren, um Aufgaben auszuführen. Beispielsweise muss ein Agent möglicherweise auf einen Vektorsuchindex zugreifen, um unstrukturierte Daten abzufragen.

Ihr Agent kann eine der folgenden Methoden verwenden, um sich bei abhängigen Ressourcen zu authentifizieren, wenn Sie sie hinter einem Model Serve-Endpunkt bereitstellen:

  1. Automatischer Authentifizierungspassthrough: Beim Protokollieren werden Databricks-Ressourcenabhängigkeiten für Ihren Agent deklariert. Databricks kann kurzlebige Anmeldeinformationen nach der Bereitstellung des Agents automatisch bereitstellen, rotieren und verwalten, um einen sicheren Zugriff auf Ressourcen zu ermöglichen. Databricks empfiehlt nach Möglichkeit die Verwendung der automatischen Authentifizierungsdurchlauf.
  2. Manuelle Authentifizierung: Bei der Agent-Bereitstellung werden langlebige Anmeldeinformationen manuell angegeben. Verwenden Sie die manuelle Authentifizierung für Databricks-Ressourcen, die keine automatische Authentifizierungspassthrough oder für externen API-Zugriff unterstützen.

Passthrough für die automatische Authentifizierung

Die Modellbereitstellung unterstützt die automatische Authentifizierung für die gängigsten Arten von Databricks-Ressourcen, die von Agenten verwendet werden.

Zum Aktivieren des automatischen Authentifizierungspassthrough müssen Sie Abhängigkeiten während der Agent-Protokollierung angeben.

Wenn Sie dann den Agent hinter einem Endpunkt bedienen, führt Databricks die folgenden Schritte aus:

  1. Berechtigungsüberprüfung: Databricks überprüft, ob die Person, die den Endpunkt erstellt hat, auf alle während der Agent-Protokollierung angegebenen Abhängigkeiten zugreifen kann.

  2. Erstellung des Dienstprinzipals und Erteilung von Berechtigungen: Ein Dienstprinzipal wird für die Version des Agent-Modells erstellt und erhält automatisch Lesezugriff auf Agent-Ressourcen.

    Hinweis

    Der vom System generierte Dienstprinzipal wird nicht in API- oder UI-Auflistungen angezeigt. Wenn die Version des Agent-Modells aus dem Endpunkt entfernt wird, wird der Dienstprinzipal ebenfalls gelöscht.

  3. Bereitstellung und Rotation von Anmeldeinformationen: Kurzlebige Anmeldeinformationen (ein M2M-OAuth-Token) für den Dienstprinzipal werden in den Endpunkt eingefügt, damit Agent-Code auf Databricks-Ressourcen zugreifen kann. Databricks wechselt auch die Anmeldeinformationen, um sicherzustellen, dass Ihr Agent weiterhin sicheren Zugriff auf abhängige Ressourcen hat.

Dieses Authentifizierungsverhalten ähnelt dem Verhalten "Als Besitzer ausführen" für Databricks-Dashboards. Der Zugriff auf nachgeschaltete Ressourcen wie Unity Catalog-Tabellen erfolgt mithilfe der Anmeldeinformationen eines Dienstprinzipals mit minimalem Zugriffsrecht auf abhängige Ressourcen.

In der folgenden Tabelle sind die Databricks-Ressourcen aufgeführt, die die automatische Authentifizierungsdurchführung unterstützen, und die Berechtigungen, die der Ersteller des Endpoints bei der Bereitstellung des Agents besitzen muss.

Hinweis

Unity-Katalogressourcen erfordern außerdem USE SCHEMA für das übergeordnete Schema und USE CATALOG im übergeordneten Katalog.

Ressourcentyp Berechtigung
SQL Warehouse Endpunkt verwenden
Endpunkt für Modellbereitstellung Abfragen
Unity-Katalogfunktion Führen Sie
Genie Space Kann ausführen
Vektorsuchindex Kann verwenden
Unity-Katalogtabelle SELECT

Manuelle Authentifizierung

Sie können Anmeldeinformationen auch manuell mithilfe von geheimnisbasierten Umgebungsvariablen bereitstellen. Die manuelle Authentifizierung kann in den folgenden Szenarien hilfreich sein:

  • Die abhängige Ressource unterstützt keinen automatischen Authentifizierungspassthrough.
  • Der Agent greift auf eine externe Ressource oder API zu.
  • Der Agent muss andere Anmeldeinformationen als die Person verwenden, die den Agent bereitstellt.

Um beispielsweise das Databricks SDK in Ihrem Agent für den Zugriff auf andere abhängige Ressourcen zu verwenden, können Sie die umgebungsvariablen festlegen, die in Databricks Client unified authenticationbeschrieben werden.

Bereitgestellte Anwendungen abrufen

Im Folgenden wird gezeigt, wie Sie Ihre bereitgestellten Agents abrufen.

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

Bereitstellen von Feedback zu einem bereitgestellten Agent (experimentell)

Wenn Sie Ihren Agent mit agents.deploy()dem Agent bereitstellen, erstellt und stellt das Agent-Framework auch eine "Feedback"-Modellversion innerhalb desselben Endpunkts bereit, die Sie abfragen können, um Feedback zu Ihrer Agentanwendung bereitzustellen. Feedbackeinträge werden als Anforderungszeilen in der Rückschlusstabelle angezeigt, die Ihrem Agent-Dienstendpunkt zugeordnet ist.

Beachten Sie, dass dieses Verhalten experimentell ist: Databricks kann eine erstklassige API bereitstellen, um Feedback zu einem bereitgestellten Agent in der Zukunft bereitzustellen, und zukünftige Funktionen erfordern möglicherweise die Migration zu dieser API.

Zu den Einschränkungen dieser API gehören:

  • Die Feedback-API hat keine Eingabeüberprüfung – sie reagiert immer erfolgreich, auch wenn ungültige Eingaben bestanden wurden.
  • Die Feedback-API erfordert die Übergabe der von Databricks generierten request_id Agent-Endpunktanforderung, zu der Sie Feedback geben möchten. Um das databricks_request_idElement abzurufen, schließen Sie {"databricks_options": {"return_trace": True}} ihre ursprüngliche Anforderung an den Agent ein, der den Endpunkt bedient. Die Agentendpunktantwort schließt dann die databricks_request_id ein, die der Anforderung zugeordnet ist, sodass Sie diese Anforderungs-ID zurück an die Feedback-API übergeben können, wenn Sie Feedback zur Agentantwort bereitstellen.
  • Feedback wird mithilfe von Rückschlusstabellen gesammelt. Siehe Einschränkungstabellenbeschränkungen.

Die folgende Beispielanforderung gibt Feedback zum Agentendpunkt mit dem Namen "Your-agent-endpoint-name" und geht davon aus, dass die DATABRICKS_TOKEN Umgebungsvariable auf ein Databricks-REST-API-Token festgelegt ist.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about Delta Live Tables"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

Sie können zusätzliche oder unterschiedliche Schlüsselwertpaare in den text_assessments.ratingsretrieval_assessments.ratings Feldern übergeben, um verschiedene Arten von Feedback bereitzustellen. Im Beispiel gibt die Feedbacknutzlast an, dass die Antwort des Agents auf die Anforderung mit der ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 korrekt, korrekt und im Kontext geerdet wurde, der von einem Retriever-Tool abgerufen wurde.

Zusätzliche Ressourcen