Sdílet prostřednictvím

Vytvoření nástrojů agenta AI pomocí funkcí katalogu Unity

Pomocí funkcí katalogu Unity můžete vytvářet nástroje agenta AI, které provádějí vlastní logiku a provádějí konkrétní úlohy, které rozšiřují možnosti LLM nad rámec generování jazyka.

Výstraha

Spuštění libovolného kódu v nástroji agenta může vystavit citlivé nebo soukromé informace, ke kterým má agent přístup. Zákazníci zodpovídají za spouštění pouze důvěryhodného kódu a implementaci mantinely a správných oprávnění, aby zabránili neúmyslnému přístupu k datům.

Požadavky

Pokud chcete vytvářet a používat funkce katalogu Unity jako nástroje agenta AI, potřebujete následující:

  • Databricks Runtime: Použijte Databricks Runtime 15.0 a vyšší
  • Verze Pythonu: Instalace Pythonu 3.10 nebo novější

Spuštění funkcí katalogu Unity:

  • Aby bylo možné spouštět funkce Katalogu Unity jako nástroje agenta AI v produkčním prostředí, musí být ve vašem pracovním prostoru povolené bezserverové výpočetní prostředí. Viz požadavky na výpočetní prostředky bez serveru.
    • Spuštění místního režimu pro funkce Pythonu nevyžaduje spuštění bezserverového obecného výpočetního prostředí, ale místní režim je určený pouze pro účely vývoje a testování.

Vytvoření funkcí katalogu Unity:

  • Aby bylo možné vytvářet funkce pomocí klienta pracovního prostoru Databricks nebo příkazů textu SQL, musí být ve vašem pracovním prostoru povolené bezserverové obecné výpočetní prostředky.
    • Funkce v Pythonu lze vytvářet i bez použití serverless computingu.

Vytvořte nástroj agenta

V tomto příkladu vytvoříte nástroj Katalogu Unity, otestujete jeho funkce a přidáte ho do agenta. V poznámkovém bloku Databricks spusťte následující kód.

Nainstalujte závislosti

Nainstalujte balíčky AI katalogu Unity s dalšími [databricks] balíčky a nainstalujte integrační balíček Databricks-LangChain.

Tento příklad používá LangChain, ale podobný přístup lze použít i na jiné knihovny. Viz Integrace nástrojů katalogu Unity s rozhraními generování AI třetích stran.

# Install Unity Catalog AI integration packages with the Databricks extra
%pip install unitycatalog-ai[databricks]
%pip install unitycatalog-langchain[databricks]

# Install the Databricks LangChain integration package
%pip install databricks-langchain

dbutils.library.restartPython()

Inicializace klienta funkce Databricks

Inicializace klienta funkce Databricks, což je specializované rozhraní pro vytváření, správu a spouštění funkcí katalogu Unity v Databricks.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Definování logiky nástroje

Nástroje katalogu Unity jsou ve skutečnosti jen uživatelem definované funkce (UDF) v Unity Catalog. Při definování nástroje Unity Catalog zaregistrujete funkci v Katalogu Unity. Další informace o uživatelem definovaných funkcích katalogu Unity najdete v tématu Uživatelem definované funkce (UDF) v katalogu Unity.

Funkce katalogu Unity můžete vytvořit pomocí jednoho ze dvou rozhraní API:

  • create_python_function přijímá funkci v Pythonu.
  • create_function přijímá SQL příkaz pro vytvoření funkce. Viz Vytvoření funkcí Pythonu.

create_python_function K vytvoření funkce použijte rozhraní API.

Aby byla vaše funkce rozpoznatelná pro datový model funkcí Unity Catalog, musí splňovat následující kritéria:

  • Rady typu: Podpis funkce musí definovat platné rady typu Pythonu. Pojmenované argumenty i návratová hodnota musí mít definované typy.
  • Nepoužívejte argumenty proměnných: Argumenty proměnných, jako jsou *args a **kwargs, nejsou podporovány. Všechny argumenty musí být explicitně definovány.
  • Kompatibilita typů: Sql nepodporuje všechny typy Pythonu. Viz podporované datové typy Sparku.
  • Popisné dokumenty: Sada nástrojů funkcí katalogu Unity čte, analyzuje a extrahuje důležité informace z docstringu.
    • Řetězce docstring musí být formátované podle syntaxe docstringu Google.
    • Napište jasné popisy vaší funkce a jejích argumentů, které pomohou LLM pochopit, jak a kdy tuto funkci používat.
  • Importy závislostí: Knihovny musí být importovány uvnitř těla funkce. Importy mimo funkci nebudou při spuštění nástroje vyřešeny.

Následující fragmenty kódu používají create_python_function k registraci volatelného objektu Pythonu add_numbers.


CATALOG = "my_catalog"
SCHEMA = "my_schema"

def add_numbers(number_1: float, number_2: float) -> float:
  """
  A function that accepts two floating point numbers adds them,
  and returns the resulting sum as a float.

  Args:
    number_1 (float): The first of the two numbers to add.
    number_2 (float): The second of the two numbers to add.

  Returns:
    float: The sum of the two input numbers.
  """
  return number_1 + number_2

function_info = client.create_python_function(
  func=add_numbers,
  catalog=CATALOG,
  schema=SCHEMA,
  replace=True
)

Testování funkce

Otestujte funkci a zkontrolujte, jestli funguje podle očekávání. Zadejte plně kvalifikovaný název funkce v execute_function rozhraní API pro spuštění funkce:

result = client.execute_function(
  function_name=f"{CATALOG}.{SCHEMA}.add_numbers",
  parameters={"number_1": 36939.0, "number_2": 8922.4}
)

result.value # OUTPUT: '45861.4'

Zabalte funkci pomocí UCFunctionToolKit

Zabalte funkci pomocí UCFunctionToolkit, aby byla přístupná knihovnám pro vytváření agentů. Sada nástrojů zajišťuje konzistenci napříč různými knihovnami generativní umělé inteligence a přidává užitečné funkce, jako je automatické trasování pro vyhledávače.

from databricks_langchain import UCFunctionToolkit

# Create a toolkit with the Unity Catalog function
func_name = f"{CATALOG}.{SCHEMA}.add_numbers"
toolkit = UCFunctionToolkit(function_names=[func_name])

tools = toolkit.tools

Použití nástroje v agentu

Přidejte pomocí vlastnosti tools nástroj do agenta LangChain z UCFunctionToolkit.

Poznámka:

V tomto příkladu se používá LangChain. Nástroje Katalogu Unity ale můžete integrovat s jinými architekturami, jako jsou LlamaIndex, OpenAI, Anthropic a další. Viz Integrace nástrojů katalogu Unity s rozhraními generování AI třetích stran.

V tomto příkladu autoři pro zjednodušení používají jednoduchého agenta využívajícího rozhraní LangChain AgentExecutor API. V případě produkčních úloh použijte pracovní postup vytváření agentů, který je vidět v ResponsesAgent příkladech.

from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.prompts import ChatPromptTemplate
from databricks_langchain import (
  ChatDatabricks,
  UCFunctionToolkit,
)
import mlflow

# Initialize the LLM (optional: replace with your LLM of choice)
LLM_ENDPOINT_NAME = "databricks-meta-llama-3-3-70b-instruct"
llm = ChatDatabricks(endpoint=LLM_ENDPOINT_NAME, temperature=0.1)

# Define the prompt
prompt = ChatPromptTemplate.from_messages(
  [
    (
      "system",
      "You are a helpful assistant. Make sure to use tools for additional functionality.",
    ),
    ("placeholder", "{chat_history}"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
  ]
)

# Enable automatic tracing
mlflow.langchain.autolog()

# Define the agent, specifying the tools from the toolkit above
agent = create_tool_calling_agent(llm, tools, prompt)

# Create the agent executor
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
agent_executor.invoke({"input": "What is 36939.0 + 8922.4?"})

Vylepšení volání nástrojů pomocí jasné dokumentace

Dobrá dokumentace pomáhá vašim agentům zjistit, kdy a jak jednotlivé nástroje používat. Při dokumentování nástrojů postupujte podle těchto osvědčených postupů:

  • Pro funkce katalogu Unity použijte COMMENT klauzuli k popisu funkčnosti a parametrů nástrojů.
  • Jasně definovat očekávané vstupy a výstupy.
  • Napište smysluplné popisy, které usnadňují používání nástrojů pro agenty a lidi.

Příklad: Efektivní dokumentace k nástrojům

Následující příklad ukazuje jasné COMMENT řetězce pro nástroj, který dotazuje strukturovanou tabulku.

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer whose info to look up.'
)
RETURNS STRING
COMMENT 'Returns metadata about a specific customer including their email and ID.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

Příklad: Neefektivní dokumentace k nástrojům

V následujícím příkladu chybí důležité podrobnosti, což ztěžuje efektivní používání nástroje agenty:

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer.'
)
RETURNS STRING
COMMENT 'Returns info about a customer.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM main.default.customer_data
  WHERE customer_name = customer_name
  LIMIT 1;

Spouštění funkcí pomocí bezserverového nebo místního režimu

Když služba generativní AI určí, že je potřeba použít nástroj, integrační balíčky (UCFunctionToolkit instance) spustí DatabricksFunctionClient.execute_function rozhraní API.

Volání execute_function může spouštět funkce ve dvou režimech spuštění: bezserverové nebo místní. Tento režim určuje, který prostředek funkci spouští.

Bezserverový režim pro produkční prostředí

Bezserverový režim je výchozí a doporučená možnost pro případy použití v produkčním prostředí při spouštění funkcí katalogu Unity jako nástroje agenta AI. Tento režim používá bezserverové obecné výpočetní prostředky (Bezserverové připojení Spark Connect) ke vzdálenému spouštění funkcí a zajišťuje, aby proces vašeho agenta zůstal zabezpečený a bez rizik spuštění libovolného kódu místně.

Poznámka:

Funkce katalogu Unity spuštěné jako nástroje agenta AI vyžadují bezserverové obecné výpočetní prostředky (Spark Connect serverless), nikoli bezserverové SQL sklady. Pokusy o spuštění nástrojů bez bezserverového obecného výpočetního prostředí způsobí chyby jako PERMISSION_DENIED: Cannot access Spark Connect.

# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="serverless")

Když váš agent požádá o spuštění nástroje v bezserverovém režimu, stane se toto:

  1. Pokud definice není místně uložena do mezipaměti, odešle DatabricksFunctionClient požadavek do katalogu Unity Catalog, aby načetl definici funkce.
  2. DatabricksFunctionClient extrahuje definici funkce a ověří názvy a typy parametrů.
  3. Odešle DatabricksFunctionClient spuštění jako UDF do bezserverového obecného výpočetního prostředí.

Místní režim vývoje

Místní režim spouští funkce Pythonu v místním podprocesu místo provádění požadavků na bezserverové obecné výpočetní prostředky. Díky tomu můžete efektivněji řešit problémy s voláními nástrojů tím, že poskytnete trasování místního zásobníku. Je navržený pro vývoj a ladění funkcí katalogu Unity Pythonu.

Když agent požádá o spuštění nástroje v místním režimu, DatabricksFunctionClient provede následující kroky:

  1. Odešle požadavek do katalogu Unity, aby načetl definici funkce, pokud nebyla definice místně uložena do mezipaměti.
  2. Extrahuje definici volatelné funkce nebo objektu, uloží si do mezipaměti lokálně a ověřuje názvy a typy parametrů.
  3. Vyvolá funkci se zadanými parametry v omezeném podprocesu s ochranou proti překročení časového limitu.
# Defaults to serverless if `execution_mode` is not specified
client = DatabricksFunctionClient(execution_mode="local")

Běh v "local" režimu poskytuje následující výhody:

  • Časový limit procesoru: Omezuje celkový modul runtime procesoru pro volatelné spouštění, aby se zabránilo nadměrnému výpočetnímu zatížení.

    Časový limit procesoru je založený na skutečném využití procesoru, nikoli na hodinovém čase. Vzhledem k plánování systému a souběžným procesům může čas procesoru v reálných scénářích překročit hodinový čas.

  • Limit paměti: Omezí virtuální paměť přidělenou procesu.

  • Ochrana časového limitu: Vynucuje celkový časový limit skutečného času pro spuštěné funkce.

Přizpůsobte si tato omezení pomocí proměnných prostředí (přečtěte si další informace).

Omezení místního režimu

  • Pouze funkce Pythonu: Funkce založené na SQL nejsou podporovány v místním režimu.
  • Aspekty zabezpečení pro nedůvěryhodný kód: Zatímco místní režim spouští funkce v podprocesu pro izolaci procesů, existuje potenciální bezpečnostní riziko při provádění libovolného kódu generovaného systémy AI. Jedná se především o problém, když se funkce spouštějí dynamicky generovaný kód Pythonu, který nebyl zkontrolován.
  • Rozdíly ve verzi knihovny: Verze knihoven se můžou lišit mezi bezserverovými a místními spouštěcími prostředími, což může vést k odlišnému chování funkce.

Proměnné prostředí

Nakonfigurujte, jak se funkce spouštějí v DatabricksFunctionClient pomocí následujících proměnných prostředí:

Proměnná prostředí Výchozí hodnota Popis
EXECUTOR_MAX_CPU_TIME_LIMIT 10 sekundy Maximální povolená doba provádění procesoru (pouze místní režim).
EXECUTOR_MAX_MEMORY_LIMIT 100 MB Maximální povolené přidělení virtuální paměti pro proces (pouze místní režim).
EXECUTOR_TIMEOUT 20 sekundy Maximální celková doba nástěnných hodin (pouze místní režim).
UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS 5 Maximální počet pokusů o opakování aktualizace klienta relace v případě vypršení platnosti tokenu.
UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT 100 Maximální počet řádků, které se mají vrátit při spouštění funkcí pomocí bezserverových výpočetních prostředků a databricks-connect.

Další kroky

  • Last updated on