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 der Kette im Unity Catalog.

  • 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 deploy()die Bereitstellungsendpunkte übergebenscale_to_zero_enabled=True. Siehe Endpunktskalierungserwartungen.
    • Rückschlusstabellen sind für diese Model Serving-Endpunkte aktiviert. Siehe Rückschlusstabellen für Überwachungs- und Debuggingmodelle.
    • Authentifizierungsanmeldeinformationen werden automatisch an alle vom Agent benötigten databricks-verwalteten Ressourcen übergeben, wie beim Protokollieren des Modells angegeben. Databricks erstellt einen Dienstprinzipal, der Zugriff auf diese Ressourcen hat, und übergibt dies automatisch an den Endpunkt. Weitere Informationen finden Sie unter Authentifizierung für abhängige Ressourcen.
  • Aktiviert die Überprüfungs-App für Ihren Agent Mit der Rezensions-App können Ihre 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

Berechtigungsanforderungen für abhängige Ressourcen

Beim Bereitstellen eines Modells mit abhängigen Ressourcen muss der Ersteller des Endpunkts je nach Ressourcentyp über die folgenden Berechtigungen verfügen:

Ressourcentyp Berechtigung
Sql Warehouse Endpunkt verwenden
Model Serving Endpoint Abfragen
Unity-Katalogfunktion Ausführen
Genie Space Ausführen
Vektorsuchindex ReadVectorIndex
Unity-Katalogtabelle Kann lesen

Authentifizierung für abhängige Ressourcen

Bei der Erstellung des Model-Serving-Endpunkts für die Agentenbereitstellung prüft Databricks, ob der Ersteller des Endpunkts die Berechtigung hat, auf alle Ressourcen zuzugreifen, von denen der Agent abhängig ist.

Für LangChain-Agents werden abhängige Ressourcen während der Agent-Erstellung und -Protokollierung automatisch abgeleitet. Diese Ressourcen werden in der Datei resources.yaml im protokollierten Modellartefakt erfasst. Während der Bereitstellung erstellt databricks.agents.deploy automatisch die M2M OAuth-Token, die erforderlich sind, um auf diese abgeleiteten Ressourcenabhängigkeiten zuzugreifen und mit ihnen zu kommunizieren.

Bei PyFunc-Agents müssen Sie alle Ressourcenabhängigkeiten während der Protokollierung des bereitgestellten Agents manuell im resources-Parameter angeben. Siehe Angeben von Ressourcen für PyFunc- oder LangChain-Agent. databricks.agents.deploy erstellt während der Bereitstellung ein M2M OAuth-Token mit Zugriff auf die im resources-Parameter angegebenen Ressourcen und stellt es für den bereitgestellten Agent bereit.

Passthrough für die automatische Authentifizierung

In der folgenden Tabelle sind die Features aufgeführt, die Passthrough für die automatische Authentifizierung unterstützen. Passthrough für die automatische Authentifizierung verwendet die Anmeldedaten des Bereitstellungserstellers, um sich automatisch bei unterstützten Features zu authentifizieren.

Funktion Mindestversion mlflow
Vektorsuchindexe Erfordert mlflow 2.13.1 oder höher
Modellbereitstellungsendpunkte Erfordert mlflow 2.13.1 oder höher
SQL-Warehouses Erfordert mlflow 2.16.1 oder höher
Unity Catalog-Funktionen Erfordert mlflow 2.16.1 oder höher

Manuelle Authentifizierung

Wenn Sie über eine abhängige Ressource verfügen, die Passthrough für die automatische Authentifizierung nicht unterstützt, oder wenn Sie andere Anmeldedaten als die des Bereitstellungserstellers verwenden möchten, können Sie Anmeldedaten manuell mithilfe Geheimnis-basierten Umgebungsvariablen bereitstellen. Wenn Sie z. B. das Databricks SDK in Ihrem Agent verwenden, um auf andere Typen abhängiger Ressourcen zuzugreifen, können Sie die Umgebungsvariablen festlegen, die in Einheitliche Databricks-Clientauthentifizierung beschrieben sind.

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 zugeordnete Anforderung ein, 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.ratings retrieval_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