Wdrażanie agenta na potrzeby generowania aplikacji sztucznej inteligencji

W tym artykule pokazano, jak wdrożyć agenta sztucznej inteligencji w usłudze Mosaic AI Model Serving przy użyciu funkcji z deploy().

Wdrażanie agentów w usłudze Mosaic AI Model Serving zapewnia następujące korzyści:

• Usługa modelowania zarządza skalowaniem automatycznym, rejestrowaniem, kontrolą wersji i kontrolą dostępu, umożliwiając skoncentrowanie się na tworzeniu agentów jakości.
• Eksperci z danej dziedziny mogą korzystać z aplikacji Przegląd w celu interakcji z wdrożonym agentem i przekazywania opinii, które można uwzględnić w monitorowaniu i ocenach.
• Można monitorować agenta, przeprowadzając ocenę ruchu na żywo. Mimo że ruch użytkowników nie będzie zawierać prawdy podstawowej, sędziowie LLM (i utworzona metryka niestandardowa) przeprowadzają ocenę nienadzorowaną.

Wymagania

• MLflow w wersji 2.13.1 lub nowszej do wdrożenia agentów za pomocą interfejsu API deploy() z databricks.agents.

• Zarejestruj agenta sztucznej inteligencji w Unity Catalog. Zobacz Rejestrowanie agenta w Unity Catalog.

• Wdrażanie agentów spoza zeszytu Databricks wymaga użycia pakietu SDK w wersji 0.12.0 lub wyższej.

• Twórca punktu końcowego (użytkownik wdrażający agenta) musi mieć CREATE VOLUME uprawnienia do schematu w katalogu Unity wybranego do przechowywania tabel wnioskowania podczas wdrażania. Dzięki temu w schemacie można utworzyć odpowiednie tabele oceny i rejestrowania. Zobacz Włączanie i wyłączanie tabel wnioskowania.

• Zainstaluj zestaw databricks-agents SDK.

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

Wdrażanie agenta przy użyciu deploy()

Użyj metody deploy(), aby wdrożyć agenta w punkcie końcowym obsługującym model.

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

Funkcja deploy() domyślnie wykonuje następujące akcje:

deploy() akcja	Opis
Tworzenie modelu procesora CPU obsługującego punkty końcowe	Sprawia, że agent jest dostępny dla aplikacji przeznaczonych dla użytkowników, obsługując go za pośrednictwem punktu końcowego obsługującego model.
Przydziel krótkotrwałe poświadczenia głównego użytkownika usługi	Usługa Databricks automatycznie udostępnia poświadczenia krótkotrwałe z minimalnymi uprawnieniami dostępu do zasobów zarządzanych przez usługę Databricks zdefiniowanych podczas rejestrowania modelu. Usługa Databricks sprawdza, czy właściciel punktu końcowego ma niezbędne uprawnienia przed wystawieniem poświadczeń, aby zapobiec eskalacji uprawnień i nieautoryzowanemu dostępowi. Zobacz Uwierzytelnianie dla zasobów zależnych. Jeśli agent zależy od zasobu niezarządzanego przez usługę Databricks, możesz przekazać zmienne środowiskowe z tajnymi wartościami do deploy(). Zobacz Konfigurowanie dostępu do zasobów z poziomu punktów końcowych obsługujących model.
Włącz aplikację przeglądową	Umożliwia uczestnikom projektu interakcję z agentem i przekazywanie opinii. Zobacz Korzystanie z aplikacji do recenzowania, umożliwiającej ludzkie recenzje aplikacji generatywnej sztucznej inteligencji (MLflow 2).
Włączanie tabel wnioskowania	Monitoruj i rozwiąż problemy agentów, rejestrując dane wejściowe i odpowiedzi na żądania. W przypadku agentów ChatAgent i ChatModel tabele wnioskowania są włączone za pomocą AI Gateway. W przypadku innych przestarzałych schematów agentów używane są standardowe tabele wnioskowania . W przypadku dzienników odpowiedzi przesyłania strumieniowego tylko pola i ślady zgodne z elementami ChatAgent i ChatCompletion są agregowane.
Rejestrowanie żądań interfejsu API REST i przeglądanie opinii o aplikacji	Rejestruje żądania interfejsu API i opinie do tabeli wnioskowania. Tworzenie modelu opinii w celu akceptowania i rejestrowania opinii z aplikacji przeglądu. Ten model jest obsługiwany w tym samym modelu procesora na tym samym punkcie końcowym co wdrożony agent.
Włącz monitorowanie Lakehouse dla Gen AI (beta)	Wymaga rejestracji w usłudze Lakehouse Monitoring for Gen AI beta. Podstawowe monitorowanie jest automatycznie włączone dla śladów wdrożonych agentów.
Włączanie śledzenia i monitorowania w czasie rzeczywistym za pomocą platformy MLflow 3 (wersja beta)	Wymaga rejestracji w wersji beta monitorowania usługi Lakehouse dla generacji AI i korzystania z biblioteki MLflow 3.0 lub nowszej. Oprócz rejestrowania śladów z wdrożonych agentów do tabel wnioskowania w celu długoterminowego przechowywania, Databricks rejestruje ślady z wdrożonego agenta do eksperymentu MLflow, aby zapewnić widoczność w czasie rzeczywistym. Zmniejsza to opóźnienia monitorowania i debugowania. Podczas tworzenia nowego punktu końcowego za pomocą agents.deploy() monitorowanie i śledzenie są skonfigurowane na potrzeby odczytu i zapisu z aktualnie aktywnego eksperymentu MLflow. Skonfiguruj eksperyment dla określonego punktu końcowego, wywołując mlflow.set_experiment() przed wywołaniem agents.deploy() w celu utworzenia punktu końcowego. Ślady wszystkich obsługiwanych agentów w punkcie końcowym (w tym agentów dodanych do punktu końcowego za pośrednictwem kolejnych wywołań do agents.deploy()) są zapisywane w tym eksperymencie. Monitorowanie oblicza metryki jakości śladów w tym eksperymencie. Domyślnie konfigurowane są tylko podstawowe metryki monitorowania. Aby dodać sędziów LLM oraz inne funkcje, zobacz Konfigurowanie monitorowania.

Uwaga

Ukończenie wdrożeń może potrwać do 15 minut. Surowe ładunki JSON docierają w ciągu 10 - 30 minut, a sformatowane dzienniki są przetwarzane z surowych ładunków mniej więcej co godzinę.

Dostosowywanie wdrożenia

Aby dostosować wdrożenie, możesz przekazać dodatkowe argumenty do elementu deploy(). Na przykład możesz włączyć skalowanie do zera dla bezczynnych punktów końcowych, przekazując scale_to_zero_enabled=True. Zmniejsza to koszty, ale zwiększa czas obsługi zapytań początkowych.

Aby uzyskać więcej parametrów, zobacz Interfejs API języka Python agentów usługi Databricks.

Pobieranie i usuwanie wdrożeń agentów

Pobieranie istniejących wdrożeń agentów lub zarządzanie nimi:

from databricks.agents import list_deployments, get_deployments, delete_deployment

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

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

Uwierzytelnianie dla zasobów zależnych

Agenci sztucznej inteligencji często muszą uwierzytelniać się w innych zasobach, aby wykonywać zadania. Na przykład agent może potrzebować dostępu do indeksu wyszukiwania wektorowego w celu wykonywania zapytań dotyczących danych bez struktury.

Twój agent może użyć jednej z następujących metod uwierzytelniania do zasobów zależnych, gdy wdrażasz go za pomocą punktu końcowego w ramach obsługi modelu.

1. Automatyczne przekazywanie uwierzytelnienia: zadeklaruj zależności zasobów usługi Databricks dla agenta podczas logowania. Usługa Databricks może automatycznie przydzielać, odnawiać i zarządzać krótkotrwałymi danymi uwierzytelniającymi, gdy agent jest wdrażany w celu bezpiecznego dostępu do zasobów. Databricks zaleca stosowanie automatycznego przekazywania uwierzytelniania tam, gdzie jest to możliwe.
2. Uwierzytelnianie w imieniu użytkownika: umożliwia uzyskiwanie dostępu do interfejsów API REST i zasobów usługi Databricks przy użyciu poświadczeń użytkownika końcowego agenta
3. Uwierzytelnianie ręczne: ręczne określanie długoterminowych poświadczeń podczas wdrażania agenta. Użyj uwierzytelniania ręcznego dla zasobów usługi Databricks, które nie obsługują automatycznego przekazywania uwierzytelniania ani dostępu do zewnętrznego interfejsu API.

automatyczne przekazywanie uwierzytelniania

Obsługa modelu zapewnia uwierzytelnianie automatyczne dla najbardziej typowych zasobów Databricks używanych przez agentów.

Aby włączyć automatyczne przekazywanie uwierzytelniania, należy określić zależności podczas logowania agenta.

Następnie, gdy obsługujesz agenta działającego za punktem końcowym, platforma Databricks wykonuje następujące kroki:

1. Weryfikacja uprawnień: Usługa Databricks sprawdza, czy twórca punktu końcowego może uzyskać dostęp do wszystkich zależności określonych podczas rejestrowania agenta.

2. Tworzenie i przydzielanie obiektu zabezpieczeń: Obiekt zabezpieczeń jest tworzony dla wersji modelu agenta i jest automatycznie przyznawany dostęp do odczytu do zasobów agenta.

   Uwaga

   Systemowo wygenerowana główna usługa nie pojawia się na listach API ani interfejsu użytkownika. Jeśli wersja modelu agenta zostanie usunięta z punktu końcowego, główny składnik usługi zostanie również usunięty.

3. Aprowizowanie i rotacja poświadczeń: poświadczenia krótkotrwałe (token OAuth M2M) dla jednostki usługi są wstrzykiwane do punktu końcowego, co umożliwia kodowi agenta uzyskiwanie dostępu do zasobów Databricks. Usługa Databricks zmienia również poświadczenia, aby zapewnić agentowi ciągły i bezpieczny dostęp do zasobów zależnych.

To zachowanie uwierzytelniania jest podobne do działania "Uruchom jako właściciel" w przypadku pulpitów nawigacyjnych Databricks – zasoby podrzędne, takie jak tabele w Unity Catalog, są dostępne przy użyciu poświadczeń jednostki usługi, która ma minimalne uprawnienia do zasobów zależnych.

W poniższej tabeli wymieniono zasoby Databricks, obsługujące automatyczne przekazywanie uwierzytelniania, oraz uprawnienia, które twórca punktu końcowego musi posiadać podczas wdrażania agenta.

Uwaga

Zasoby Katalogu Unity wymagają USE SCHEMA dla schematu nadrzędnego i USE CATALOG dla katalogu nadrzędnego.

Typ zasobu	Uprawnienie
SQL Warehouse	Użyj punktu końcowego
Punkt końcowy serwisowania modelu	Może wykonywać zapytania
Funkcja Katalogu Unity	WYKONAJ
Genie Space	Możliwość uruchomienia
Indeks wyszukiwania wektorowego	Może korzystać
Tabela katalogu Unity	SELECT

Uwierzytelnianie w imieniu użytkownika

Uwierzytelnianie w imieniu użytkownika umożliwia deweloperom agentów dostęp do poufnych zasobów usługi Databricks przy użyciu poświadczeń użytkownika końcowego agenta. Aby włączyć dostęp w imieniu użytkownika do zasobów, wykonaj dwa kroki:

1. W kodzie agenta upewnij się, że zasób usługi Databricks jest uzyskiwany za pomocą klienta z włączonym uwierzytelnianiem w imieniu użytkownika. Aby uzyskać więcej informacji, zobacz Deploy an agent using on-behalf-of-user authentication (Wdrażanie agenta przy użyciu uwierzytelniania w imieniu użytkownika ).
2. Podczas rejestrowania agenta określ zakresy interfejsu API REST użytkownika końcowego (na przykład vectorsearch.vector-search-endpoints) wymagane przez agenta. Po wdrożeniu agenta może on uzyskiwać dostęp do zasobów usługi Databricks w imieniu użytkownika końcowego, ale tylko przy użyciu określonych zakresów. Aby uzyskać więcej informacji na temat zakresów interfejsu API, zobacz On-behalf-of-user authentication (Uwierzytelnianie w imieniu użytkownika).

Uwierzytelnianie ręczne

Możesz również ręcznie podać poświadczenia przy użyciu zmiennych środowiskowych opartych na sekretach. Uwierzytelnianie ręczne może być przydatne w następujących scenariuszach:

• Zasób zależny nie obsługuje automatycznego przekazywania danych uwierzytelniających.
• Agent uzyskuje dostęp do zewnętrznego zasobu lub interfejsu API.
• Agent musi używać poświadczeń innych niż te używane przez wdrażającego agenta.

Aby na przykład użyć zestawu SDK usługi Databricks w agencie w celu uzyskania dostępu do innych zasobów zależnych, możesz ustawić zmienne środowiskowe opisane w temacie Ujednolicone uwierzytelnianie klienta usługi Databricks.

Monitoruj wdrożonych agentów

Po wdrożeniu agenta w usłudze Databricks Model Serving można użyć tabel wnioskowania AI Gateway do monitorowania uruchomionego agenta. Tabele wnioskowania zawierają szczegółowe dzienniki żądań, odpowiedzi, ślady agentów i opinie agentów z systemu przeglądu. Te informacje umożliwiają debugowanie problemów, monitorowanie wydajności i tworzenie złotego zestawu danych na potrzeby oceny w trybie offline.

Ważne

Jeśli w twoim środowisku deweloperskim jest zainstalowane MLflow 3, kiedy wywołujesz agents.deploy(), twój punkt końcowy będzie zapisywać ślady MLflow w czasie rzeczywistym do eksperymentu MLflow aktywowanego w momencie wywołania agents.deploy(). Możesz zadzwonić pod mlflow.set_experiment(), aby zmienić aktywny eksperyment przed wdrożeniem.

Aby uzyskać więcej informacji, zobacz dokumentację platformy MLflow .

Zobacz Debugowanie i obserwowanie aplikacji za pomocą śledzenia.

Pobieranie wdrożonych aplikacji

Poniżej przedstawiono, jak uzyskać dostęp do wdrożonych agentów.

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

Zobacz Interfejs API języka Python agentów usługi Databricks.

Przekazywanie opinii na temat wdrożonego agenta (eksperymentalne)

Podczas wdrażania agenta za pomocą agents.deploy(), platforma agenta tworzy i wdraża także wersję modelu "feedback" w tym samym punkcie końcowym, do którego można wysyłać zapytania w celu przekazania opinii na temat aplikacji agenta. Wpisy opinii są wyświetlane jako wiersze żądań w tabeli wnioskowania skojarzonej z punktem końcowym obsługującym agenta.

Należy pamiętać, że to zachowanie jest eksperymentalne: usługa Databricks może zapewnić najwyższej klasy interfejs API do przekazywania opinii na temat wdrożonego agenta w przyszłości, a przyszłe funkcje mogą wymagać migracji do tego interfejsu API.

Ograniczenia tego interfejsu API obejmują:

• Interfejs API opinii nie ma weryfikacji danych wejściowych — zawsze reaguje pomyślnie, nawet jeśli przekazano nieprawidłowe dane wejściowe.
• Interfejs API opinii wymaga przekazania wygenerowanego przez Databricks request_id żądania punktu końcowego agenta, dla którego chcesz przekazać opinię. Aby pobrać element databricks_request_id, dołącz {"databricks_options": {"return_trace": True}} do oryginalnego żądania do agenta obsługującego punkt końcowy. Odpowiedź punktu końcowego agenta będzie następnie zawierać databricks_request_id skojarzone z żądaniem, aby można było przekazać ten identyfikator żądania z powrotem do interfejsu API opinii podczas przekazywania uwag dotyczących odpowiedzi agenta.
• Opinie są zbierane przy użyciu tabel wnioskowania. Zobacz ograniczenia tabeli wnioskowania.

Poniższe przykładowe żądanie zawiera opinię na temat punktu końcowego agenta o nazwie "your-agent-endpoint-name" i zakłada, że DATABRICKS_TOKEN zmienna środowiskowa jest ustawiona na token interfejsu API REST usługi Databricks.

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 Lakeflow Declarative Pipelines"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

Możesz przekazać dodatkowe lub zupełnie inne pary klucz-wartość w polach text_assessments.ratings i retrieval_assessments.ratings, aby udzielić różnych typów opinii. W tym przykładzie ładunek opinii wskazuje, że odpowiedź agenta na żądanie o identyfikatorze 573d4a61-4adb-41bd-96db-0ec8cebc3744 była poprawna, dokładna i oparta na kontekście pobranym przez narzędzie wyszukiwania.

Dodatkowe zasoby

• Zapytywanie wdrożonego agenta Mosaic AI
• Ocena agenta mozaiki sztucznej inteligencji (MLflow 2)
• Używaj aplikacji recenzującej do ludzkiej oceny aplikacji generatywnej sztucznej inteligencji (MLflow 2)
• Debugowanie wdrożonego agenta sztucznej inteligencji