Udostępnij za pośrednictwem

Wdrażanie agenta do generowania aplikacji sztucznej inteligencji

  • Artykuł

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

W tym artykule pokazano, jak wdrożyć agenta sztucznej inteligencji przy użyciu funkcji z poziomu interfejsu deploy() API języka Python platformy Agent Framework.

Wymagania

  • Narzędzie MLflow w wersji 2.13.1 lub nowszej w celu wdrożenia agentów przy użyciu interfejsu deploy() API z programu databricks.agents.

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

  • Wdrażanie agentów spoza notesu usługi Databricks wymaga pakietu SDK databricks-agents w wersji 0.12.0 lub wyższej.

  • Zainstaluj zestaw databricks-agents SDK.

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

Wdrażanie agenta przy użyciu deploy()

Funkcja deploy() wykonuje następujące czynności:

  • Tworzy model procesora CPU obsługujący punkty końcowe dla agenta, który można zintegrować z aplikacją dostępną dla użytkownika.

    Uwaga

    W przypadku dzienników odpowiedzi przesyłanych strumieniowo są agregowane tylko pola zgodne z funkcją ChatCompletion i ślady.

  • Włącza przeglądanie aplikacji dla agenta. Aplikacja Recenzji umożliwia uczestnikom projektu czat z agentem i przekazywanie opinii przy użyciu interfejsu użytkownika Aplikacji Recenzji.

  • Rejestruje każde żądanie w tabeli wnioskowania w interfejsie API przeglądu aplikacji lub interfejsu API REST. Zarejestrowane dane obejmują żądania zapytań, odpowiedzi i pośrednie dane śledzenia z śledzenia MLflow.

  • Tworzy model opinii z tym samym wykazem i schematem co agent, który próbujesz wdrożyć. Ten model opinii to mechanizm, który umożliwia akceptowanie opinii z aplikacji Przegląd i rejestrowanie jej w tabeli wnioskowania. Ten model jest obsługiwany w tym samym modelu procesora CPU obsługującym punkt końcowy, co wdrożony agent. Ponieważ ten punkt końcowy obsługujący ma włączone tabele wnioskowania, można rejestrować opinie z aplikacji przeglądu do tabeli wnioskowania.

Uwaga

Ukończenie wdrożeń może potrwać do 15 minut. Nieprzetworzone ładunki JSON trwają od 10 do 30 minut, a sformatowane dzienniki są przetwarzane z nieprzetworzonych ładunków około każdej godziny.


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

Tabele wnioskowania rozszerzonego agenta

Funkcja deploy() tworzy trzy tabele wnioskowania dla każdego wdrożenia w celu rejestrowania żądań i odpowiedzi do i z punktu końcowego obsługującego agenta. Użytkownicy mogą oczekiwać, że dane będą znajdować się w tabeli ładunków w ciągu godziny od interakcji z ich wdrożeniem.

Wypełnianie dzienników żądań ładunku i dzienników oceny może trwać dłużej, ale ostatecznie pochodzi z tabeli nieprzetworzonego ładunku. Dzienniki żądań i ocen można wyodrębnić samodzielnie z tabeli ładunków. Usunięcia i aktualizacje tabeli ładunku nie są odzwierciedlane w dziennikach żądań ładunku ani w dziennikach oceny ładunku.

Uwaga

Jeśli masz włączoną zaporę usługi Azure Storage, skontaktuj się z zespołem konta usługi Databricks, aby włączyć tabele wnioskowania dla punktów końcowych.

Table Przykładowa nazwa tabeli wykazu aparatu Unity Co znajduje się w każdej tabeli
Ładunek {catalog_name}.{schema_name}.{model_name}_payload Nieprzetworzone ładunki żądań JSON i odpowiedzi
Dzienniki żądań ładunku {catalog_name}.{schema_name}.{model_name}_payload_request_logs Sformatowane żądania i odpowiedzi, ślady MLflow
Dzienniki oceny ładunku {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Sformatowane opinie, jak podano w aplikacji Przegląd, dla każdego żądania

Poniżej przedstawiono schemat tabeli dzienników żądań.

Nazwa kolumny Type opis
client_request_id String Identyfikator żądania klienta, zazwyczaj null.
databricks_request_id String Identyfikator żądania usługi Databricks.
date Data Data żądania.
timestamp_ms Długi Sygnatura czasowa w milisekundach.
timestamp Sygnatura czasowa Sygnatura czasowa żądania.
status_code Integer Kod stanu punktu końcowego.
execution_time_ms Długi Łączna liczba milisekund wykonania.
conversation_id String Identyfikator konwersacji wyodrębniony z dzienników żądań.
request String Ostatnie zapytanie użytkownika z konwersacji użytkownika. Jest to wyodrębnione z żądania RAG.
response String Ostatnia odpowiedź na użytkownika. Jest to wyodrębnione z żądania RAG.
request_raw String Reprezentacja ciągu żądania.
response_raw String Reprezentacja ciągu odpowiedzi.
trace String Reprezentacja ciągu śledzenia wyodrębnionego z databricks_options struktury odpowiedzi.
sampling_fraction Liczba rzeczywista Ułamek próbkowania.
request_metadata Map[String, String] Mapa metadanych związanych z modelem obsługującym punkt końcowy skojarzony z żądaniem. Ta mapa zawiera nazwę punktu końcowego, nazwę modelu i wersję modelu używaną dla punktu końcowego.
schema_version String Liczba całkowita dla wersji schematu.

Poniżej przedstawiono schemat tabeli dzienników oceny.

Nazwa kolumny Type opis
request_id String Identyfikator żądania usługi Databricks.
step_id String Pochodzi z oceny pobierania.
source Struktura Pole struktury zawierające informacje o tym, kto utworzył ocenę.
timestamp Sygnatura czasowa Sygnatura czasowa żądania.
text_assessment Struktura Pole struktury zawierające dane dotyczące wszelkich opinii na temat odpowiedzi agenta z aplikacji do przeglądu.
retrieval_assessment Struktura Pole struktury zawierające dane dotyczące wszelkich opinii na temat dokumentów pobranych na odpowiedź.

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 do uwierzytelniania w zasobach zależnych, gdy znajduje się za punktem końcowym obsługi modelu.

  1. Automatyczne przekazywanie uwierzytelnienia: Deklarowanie zależności zasobów 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. ręczne uwierzytelnianie: ręcznie określ poświadczenia o długiej ważności 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.

Przekazywanie uwierzytelniania automatycznego

Serwowanie modelu zapewnia automatyczne przekazywanie uwierzytelniania dla najbardziej typowych zasobów Databricks używanych przez agentów.

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

Następnie po obsłużeniu agenta za punktem końcowym usługa Databricks wykonuje następujące kroki:

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

  2. tworzenie i przyznawanie uprawnień jednostce usługi: jednostka usługi jest tworzona dla wersji modelu agenta i automatycznie uzyskuje 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. pl-PL: aprowizowanie i rotacja poświadczeń: Krótkotrwałe poświadczenia (token OAuth M2M) dla podmiotu usługi są umieszczane w punkcie końcowym, co umożliwia kodowi agenta dostęp do zasobów Databricks. Usługa Databricks odświeża również poświadczenia, zapewniając agentowi ciągły, bezpieczny dostęp do zasobów zależnych.

To zachowanie uwierzytelniania jest podobne do zachowania "Uruchom jako właściciel" dla pulpitów nawigacyjnych Databricks — zasoby pochodne, takie jak tabele Unity Catalog, są dostępne przy użyciu poświadczeń jednostki usługi z uprawnieniami o najniższym poziomie do zasobów zależnych.

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

Uwaga

Zasoby Katalogu Unity wymagają USE SCHEMA w schemacie nadrzędnym i USE CATALOG w katalogu nadrzędnym.

Typ zasobu Uprawnienie
SQL Warehouse Korzystanie z punktu końcowego
Punkt końcowy obsługi modelu Może wykonywać zapytania
Funkcja wykazu aparatu Unity WYKONAĆ
Przestrzeń Genie Można uruchomić
Indeks wyszukiwania wektorowego Może używać
Tabela wykazu aparatu Unity SELECT

Uwierzytelnianie ręczne

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

  • Zasób zależny nie obsługuje automatycznego przekazywania uwierzytelniania.
  • Agent uzyskuje dostęp do zewnętrznego zasobu lub interfejsu API.
  • Agent musi używać poświadczeń innych niż te używane przez implementują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 jednolitym uwierzytelnianiu klienta Databricks.

Pobieranie wdrożonych aplikacji

Poniżej przedstawiono sposób uzyskiwania 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

Przekazywanie opinii na temat wdrożonego agenta (eksperymentalne)

Podczas wdrażania agenta za pomocą agents.deploy()platformy agenta platforma agenta tworzy również i wdraża wersję modelu "feedback" w tym samym punkcie końcowym, który 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 danych wygenerowanego request_id przez usługę Databricks żądania punktu końcowego agenta, na którym chcesz przekazać opinię. Aby pobrać element databricks_request_id, dołącz {"databricks_options": {"return_trace": True}} do oryginalnego żądania do punktu końcowego obsługującego agenta. 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 opinii na temat 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 Delta Live Tables"
                      }
                  ],
                  "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 różne pary klucz-wartość w polach itext_assessments.ratings, retrieval_assessments.ratings aby przekazać różne typy 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 uziemiona w kontekście pobranym przez narzędzie pobierania.

Dodatkowe zasoby