Sdílet prostřednictvím

Nasazení agenta pro aplikaci generující AI

  • Článek

Důležité

Tato funkce je ve verzi Public Preview.

Tento článek ukazuje, jak nasadit agenta AI pomocí deploy() rozhraní API z databricks.agents.

Požadavky

  • MLflow 2.13.1 nebo vyšší pro nasazení agentů pomocí deploy() rozhraní API z databricks.agents.

  • Zaregistrujte agenta AI do katalogu Unity. Viz Registrace řetězu do katalogu Unity.

  • databricks-agents Nainstalujte sadu SDK.

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

Nasazení agenta pomocí deploy()

Rozhraní deploy() API provede následující:

  • Vytvoří model procesoru obsluhující koncové body pro vašeho agenta, který je možné integrovat do aplikace určené pro uživatele.
  • Povolí aplikaci Review pro vašeho agenta. Aplikace Review umožňuje zúčastněným stranám chatovat s agentem a poskytovat zpětnou vazbu pomocí uživatelského rozhraní aplikace Revize.
  • Protokoluje všechny požadavky do tabulky odvozování aplikace nebo rozhraní REST API. Protokolovaná data zahrnují požadavky na dotazy, odpovědi a zprostředkující data trasování z trasování MLflow.
  • Vytvoří model zpětné vazby se stejným katalogem a schématem jako agent, který se pokoušíte nasadit. Tento model zpětné vazby je mechanismus, který umožňuje přijmout zpětnou vazbu z aplikace review a protokolovat ji do tabulky odvozování. Tento model se obsluhuje ve stejném modelu procesoru, který slouží koncovému bodu jako nasazený agent. Vzhledem k tomu, že tento koncový bod obsluhy má povolené tabulky odvozování, je možné protokolovat zpětnou vazbu z aplikace Review do tabulky odvozování.

Poznámka:

Dokončení nasazení může trvat až 15 minut. Doručení nezpracovaných datových částí JSON trvá 10 až 30 minut a formátované protokoly se zpracovávají z nezpracovaných datových částí přibližně každou hodinu.


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

Tabulky odvození rozšířeného agenta

Vytvoří deploy() tři tabulky odvozování pro každé nasazení za účelem protokolování požadavků a odpovědí do a z koncového bodu obsluhujícího agenta. Uživatelé můžou očekávat, že data budou v tabulce datové části do hodiny od interakce s nasazením.

Naplnění protokolů žádostí datové části a protokolů posouzení může trvat déle, ale nakonec se odvozují z tabulky nezpracované datové části. Protokoly žádostí a posouzení můžete extrahovat sami z tabulky datové části. Odstranění a aktualizace tabulky datové části se neprojeví v protokolech žádostí o datovou část ani v protokolech posouzení datové části.

Poznámka:

Pokud máte povolenou bránu firewall služby Azure Storage, obraťte se na tým účtu Databricks a povolte tabulky odvozování pro vaše koncové body.

Table Příklad názvu tabulky katalogu Unity Co je v každé tabulce
Datová část {catalog_name}.{schema_name}.{model_name}_payload Nezpracované datové části požadavků JSON a odpovědí
Protokoly žádostí o datovou část {catalog_name}.{schema_name}.{model_name}_payload_request_logs Formátované požadavky a odpovědi, trasování MLflow
Protokoly posouzení datové části {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Naformátovaná zpětná vazba, jak je uvedeno v aplikaci pro kontrolu, pro každý požadavek

Následující příklad ukazuje schéma tabulky protokolů požadavků.

Název sloupce Typ Description
client_request_id String ID požadavku klienta, obvykle null.
databricks_request_id String ID požadavku Databricks
date Datum Datum žádosti.
timestamp_ms Dlouhé celé číslo Časové razítko v milisekundách
timestamp Časové razítko Časové razítko požadavku.
status_code Celé číslo Stavový kód koncového bodu
execution_time_ms Dlouhé celé číslo Celkový počet milisekund provádění.
conversation_id String ID konverzace extrahované z protokolů požadavků
request String Poslední dotaz uživatele z konverzace uživatele. Tento požadavek se extrahuje z požadavku RAG.
response String Poslední odpověď na uživatele. Tento požadavek se extrahuje z požadavku RAG.
request_raw String Řetězcová reprezentace požadavku.
response_raw String Řetězcová reprezentace odpovědi
trace String Řetězcové znázornění trasování extrahovaného ze databricks_options struktury odpovědi
sampling_fraction Hodnota s dvojitou přesností Vzorkování zlomku.
request_metadata Map[Řetězec, Řetězec] Mapa metadat souvisejících s koncovým bodem obsluhující model přidružený k požadavku Tato mapa obsahuje název koncového bodu, název modelu a verzi modelu používanou pro váš koncový bod.
schema_version String Celé číslo pro verzi schématu.

Následuje schéma tabulky protokolů posouzení.

Název sloupce Typ Description
request_id String ID požadavku Databricks
step_id String Odvozeno z posouzení načítání.
source Struktura Pole struktury obsahující informace o tom, kdo posouzení vytvořil.
timestamp Časové razítko Časové razítko požadavku.
text_assessment Struktura Pole struktury obsahující data pro jakoukoli zpětnou vazbu k odpovědím agenta z aplikace pro kontrolu
retrieval_assessment Struktura Pole struktury obsahující data pro zpětnou vazbu k dokumentům načteným pro odpověď.

Ověřování pro závislé prostředky

Při vytváření modelu obsluhujícího koncový bod pro nasazení agenta Databricks ověří, že tvůrce koncového bodu má oprávnění pro přístup ke všem prostředkům, na kterých agent závisí.

U agentů s příchutí jazyka LangChain se závislé prostředky při vytváření a protokolování agenta automaticky odvozují. Tyto prostředky se zaprotokolují v resources.yaml souboru v artefaktu přihlášeného modelu. Během nasazování databricks.agents.deploy automaticky vytvoří tokeny M2M OAuth potřebné pro přístup a komunikaci s těmito odvozenými závislostmi prostředků.

U agentů s příchutí PyFunc je nutné během protokolování nasazeného agenta v parametru resources ručně zadat všechny závislosti prostředků. Viz Určení prostředků pro agenta PyFunc nebo LangChain. Během nasazení databricks.agents.deploy vytvoří token OAuth M2M s přístupem k prostředkům zadaným v parametru resources a nasadí ho do nasazeného agenta.

Předávání automatického ověřování

Následující tabulka uvádí funkce, které podporují předávání automatického ověřování. Předávání automatického ověřování používá přihlašovací údaje tvůrce nasazení k automatickému ověření v podporovaných funkcích.

Funkce Minimální mlflow verze
Indexy vektorových vyhledávání Vyžaduje mlflow verzi 2.13.1 nebo vyšší.
Koncové body obsluhy modelů Vyžaduje mlflow verzi 2.13.1 nebo vyšší.
SQL Warehouses Vyžaduje mlflow verzi 2.16.1 nebo vyšší.
Funkce katalogu Unity Vyžaduje mlflow verzi 2.16.1 nebo vyšší.

Ruční ověřování

Pokud máte závislý prostředek, který nepodporuje předávání automatického ověřování nebo pokud chcete použít jiné přihlašovací údaje než tvůrce nasazení, můžete přihlašovací údaje zadat ručně pomocí proměnných prostředí založených na tajných kódech. Pokud například používáte sadu Databricks SDK ve vašem agentovi pro přístup k jiným typům závislých prostředků, můžete nastavit proměnné prostředí popsané v jednotném ověřování klienta Databricks.

Získání nasazených aplikací

Následující příklad ukazuje, jak získat nasazené agenty.

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

Poskytnutí zpětné vazby k nasazeným agentem (experimentální)

Když nasadíte agenta pomocí agents.deploy()rozhraní agenta, rozhraní agenta také vytvoří a nasadí verzi modelu zpětné vazby ve stejném koncovém bodu, na který můžete zadat zpětnou vazbu k aplikaci agenta. Položky zpětné vazby se zobrazí jako řádky požadavků v tabulce odvozování přidružené ke koncovému bodu obsluhujícího agenta.

Toto chování je experimentální: Databricks může poskytnout prvotřídní rozhraní API pro poskytování zpětné vazby k nasazeným agentům v budoucnu a budoucí funkce můžou vyžadovat migraci na toto rozhraní API.

Mezi omezení tohoto rozhraní API patří:

  • Rozhraní API pro zpětnou vazbu nemá ověření vstupu – vždy úspěšně reaguje, i když bylo předáno neplatné zadání.
  • Rozhraní API pro zpětnou vazbu vyžaduje předání požadavku koncového bodu agenta vygenerovaného request_id službou Databricks, ke kterému chcete poskytnout zpětnou vazbu. Pokud chcete získat , zahrňte {"databricks_options": {"return_trace": True}} ho databricks_request_iddo původního požadavku do koncového bodu obsluhujícího agenta. Odpověď koncového bodu agenta pak zahrne přidruženou databricks_request_id k požadavku, abyste mohli toto ID požadavku předat zpět do rozhraní API pro zpětnou vazbu při poskytování zpětné vazby k odpovědi agenta.
  • Zpětná vazba se shromažďuje pomocí odvozovacích tabulek. Viz omezení odvozovací tabulky.

Následující příklad požadavku poskytuje zpětnou vazbu ke koncovému bodu agenta s názvem "your-agent-endpoint-name" a předpokládá, že DATABRICKS_TOKEN proměnná prostředí je nastavená na token rozhraní REST API 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

Do polí retrieval_assessments.ratings a polí můžete předat další nebo různé páry text_assessments.ratings klíč-hodnota a poskytnout tak různé typy zpětné vazby. V tomto příkladu datová část zpětné vazby označuje, že odpověď agenta na požadavek s ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 byla správná, přesná a uzemněná v kontextu načteného nástrojem retrieveru.

Další materiály