Bereitstellen eines Agents für generative KI-Anwendung
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 vondatabricks.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=True
die 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.
- Databricks stellt automatisch kurzlebige Dienstprinzipal-Anmeldeinformationen für Agent-Code bereit, der im Endpunkt ausgeführt wird. Die Anmeldeinformationen verfügen über die Mindestberechtigungen für den Zugriff auf von Databricks verwaltete Ressourcen, so wie es bei der Modellprotokollierung definiert wurde. Vor dem Generieren dieser Anmeldeinformationen stellt Databricks sicher, dass der Endpunktbesitzer über die entsprechenden Berechtigungen verfügt, um eine Berechtigungseskalation und nicht autorisierten Zugriff zu verhindern. Weitere Informationen finden Sie unter Authentifizierung für abhängige Ressourcen.
- Wenn Sie über Ressourcenabhängigkeiten verfügen, die nicht von Databricks verwaltet werden, z. B. mithilfe von Pinecone, können Sie Umgebungsvariablen mit geheimen Schlüsseln an die
deploy()
-API übergeben. Weitere Informationen finden Sie unter Konfigurieren des Zugriffs auf Ressourcen über Modellbereitstellungsendpunkte.
- Wenn Sie über Ressourcenabhängigkeiten verfügen, die nicht von Databricks verwaltet werden, z. B. mithilfe von Pinecone, können Sie Umgebungsvariablen mit geheimen Schlüsseln an die
- 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
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:
- 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.
- 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:
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.
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.
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 dasdatabricks_request_id
Element 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 diedatabricks_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.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.