AI-ügynökeszközök létrehozása Unity Catalog-függvényekkel

A Unity Catalog-függvényekkel olyan AI-ügynökeszközöket hozhat létre, amelyek egyéni logikát hajtanak végre, és olyan konkrét feladatokat hajtanak végre, amelyek kiterjesztik az LLM-k képességeit a nyelvgeneráláson túl.

Figyelmeztetés

Ha tetszőleges kódot hajt végre egy ügynökeszközön, az bizalmas vagy személyes adatokat tehet közzé, amelyekhez az ügynök hozzáfér. Az ügyfelek feladata, hogy csak megbízható kódot futtasson, és védőkorlátokat és megfelelő engedélyeket implementáljon az adatokhoz való nem szándékos hozzáférés megakadályozása érdekében.

Követelmények

A Unity Catalog-függvények AI-ügynökeszközként való létrehozásához és használatához a következőkre van szükség:

Databricks Runtime: A Databricks Runtime 15.0-s vagy újabb verziója
Python-verzió: A Python 3.10 vagy újabb telepítése

Unity Catalog-függvények futtatása:

A kiszolgáló nélküli számítást engedélyezni kell a munkaterületen a Unity Catalog-függvények éles környezetben történő AI-ügynökeszközként való végrehajtásához. Lásd a kiszolgáló nélküli számítási követelményeket.
- A Python-függvények helyi módú végrehajtása nem igényli a kiszolgáló nélküli általános számítás futtatását, a helyi mód azonban csak fejlesztési és tesztelési célokra szolgál.

Unity Catalog-függvények létrehozása:

A kiszolgáló nélküli általános számítást engedélyezni kell a munkaterületen a Databricks-munkaterület ügyfél- vagy SQL-törzs utasítások használatával történő függvények létrehozásához.
- A Python-függvények kiszolgáló nélküli számítás nélkül is létrehozhatók.

Ügynökeszköz létrehozása

Ebben a példában létrehoz egy Unity Catalog-eszközt, teszteli annak működését, és hozzáadja egy ügynökhöz. Futtassa a következő kódot egy Databricks-jegyzetfüzetben.

Függőségek telepítése

Telepítse a Unity Catalog AI-csomagokat az [databricks] extrával, és telepítse a Databricks-LangChain integrációs csomagot.

Ez a példa a LangChaint használja, de hasonló megközelítés alkalmazható más kódtárakra is. Lásd: Unity Catalog-eszközök integrálása harmadik féltől származó generatív AI-keretrendszerekkel.

# 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()

A Databricks Function kliens inicializálása

Inicializálja a Databricks-függvényügyfélt, amely egy speciális felület a Unity Catalog-függvények Databricksben való létrehozásához, kezeléséhez és futtatásához.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Az eszköz logikájának meghatározása

A Unity Catalog-eszközök valójában csak a háttérben működő Unity Catalog felhasználó által definiált függvények (UDF-ek). Egy Unity Catalog-eszköz definiálásakor egy függvényt regisztrál a Unity Catalogban. A Unity Catalog UDF-jeiről további információt a Felhasználó által definiált függvények (UDF-ek) a Unity Katalógusban talál.

Unity Catalog-függvényeket két API egyikével hozhat létre:

create_python_function egy Pythonban meghívható objektumot fogad el.
create_function elfogad egy SQL-törzs-létrehozási függvényutasítást. Lásd: Python-függvények létrehozása.

create_python_function Az API használatával hozza létre a függvényt.

Ahhoz, hogy a Python felismerhető legyen a Unity Catalog-függvények adatmodelljéhez, a függvénynek meg kell felelnie a következő követelményeknek:

Típustippek: A függvény-aláírásnak érvényes Python-típustippeket kell meghatároznia. A névvel ellátott argumentumoknak és a visszatérési értéknek is meg kell határozniuk a típusukat.
Ne használjon változóargumentumokat: Az olyan változóargumentumok, mint a *args és a **kwargs nem támogatottak. Minden argumentumot explicit módon kell definiálni.
Típuskompatibilitás: Az SQL nem minden Python-típust támogat. Lásd a Spark által támogatott adattípusokat.
Leíró dokumentumszkriptek: A Unity Catalog-függvények eszközkészlete felolvassa, elemzi és kinyeri a fontos információkat a dokumentumszkriptből.
- A dokumentumokat a Google docstring szintaxisa szerint kell formázni.
- Írjon egyértelmű leírásokat a függvényhez és annak argumentumaihoz, hogy az LLM megértse, hogyan és mikor érdemes használni a függvényt.
Függőségimportálás: A kódtárakat a függvény törzsén belül kell importálni. Az eszköz futtatásakor a függvényen kívüli importálások nem oldódnak fel.

A következő kódrészletek a create_python_function elemet használják a Python add_numbers meghívható regisztrálásához.


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
)

A függvény tesztelése

Tesztelje a függvényt, hogy a várt módon működik-e. Adjon meg egy teljesen minősített függvénynevet az execute_function API-ban a függvény futtatásához:

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'

A függvény körbefuttatása az UCFunctionToolKit használatával

Burkolja be a függvényt a UCFunctionToolkit használatával, hogy elérhetővé tegye az ügynökkészítő kódtárak számára. Az eszközkészlet biztosítja a konzisztenciát a különböző generációs AI-kódtárakban, és olyan hasznos funkciókat ad hozzá, mint az automatikus nyomkövetés a lekérdezők számára.

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

Az eszköz használata ügynökben

Adja hozzá az eszközt egy LangChain-ügynökhöz a tools tulajdonság használatával a UCFunctionToolkit-ből.

Megjegyzés:

Ez a példa LangChain-t használ. A Unity Catalog eszközeit azonban integrálhatja más keretrendszerekkel, például a LlamaIndexkel, az OpenAI-val, az antropikussal és más keretrendszerekkel. Lásd: Unity Catalog-eszközök integrálása harmadik féltől származó generatív AI-keretrendszerekkel.

Ez a példa egy egyszerű ügynököt ír le, amely a LangChain AgentExecutor API-t használja az egyszerűség kedvéért. Gyártási munkaterhelésekhez használja az ügynökkészítési munkafolyamatot, amely a példákban láthatóResponsesAgent.

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?"})

Az eszközhívás javítása világos dokumentációval

A jó dokumentáció segít az ügynököknek tudni, hogy mikor és hogyan kell használni az egyes eszközöket. Kövesse az alábbi ajánlott eljárásokat az eszközök dokumentálásához:

A Unity Catalog-függvények esetében használja a záradékot az COMMENT eszköz funkcióinak és paramétereinek leírására.
Egyértelműen definiálja a várt bemeneteket és kimeneteket.
Írjon értelmes leírásokat, hogy megkönnyítse az ügynökök és az emberek számára az eszközök használatát.

Példa: Hatékony eszközdokumentáció

Az alábbi példa egy strukturált táblát lekérdező eszköz egyértelmű COMMENT sztringeit mutatja be.

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élda: Hatástalan eszközdokumentáció

Az alábbi példa nem tartalmaz fontos részleteket, ami megnehezíti az ügynökök számára az eszköz hatékony használatát:

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;

Függvények futtatása kiszolgáló nélküli vagy helyi módban

Amikor egy gen AI-szolgáltatás megállapítja, hogy szükség van egy eszközhívásra, az integrációs csomagok (UCFunctionToolkit példányok) futtatják az DatabricksFunctionClient.execute_function API-t.

A execute_function hívás két végrehajtási módban futtathat függvényeket: kiszolgáló nélküli vagy helyi. Ez a mód határozza meg, hogy melyik erőforrás futtatja a függvényt.

Kiszolgáló nélküli mód éles környezetben

A kiszolgáló nélküli mód az alapértelmezett és ajánlott beállítás éles használat esetén, amikor AI-ügynökeszközként hajtja végre a Unity Catalog-függvényeket. Ez a mód kiszolgáló nélküli általános számítást (Spark Connect kiszolgáló nélküli) használ a függvények távoli végrehajtásához, biztosítva, hogy az ügynök folyamata biztonságos maradjon, és mentes legyen az tetszőleges kód helyi futtatásának kockázatától.

Megjegyzés:

Az AI-ügynökeszközökként végrehajtott Unity Catalog-függvények kiszolgáló nélküli általános számítást igényelnek (a Spark Connect kiszolgáló nélküli), nem pedig kiszolgáló nélküli SQL-raktárakat. A kiszolgáló nélküli általános számítás nélküli eszközök futtatására tett kísérletek olyan hibákat eredményeznek, mint a PERMISSION_DENIED: Cannot access Spark Connect.

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

Amikor az ügynök kiszolgáló nélküli módban kéri az eszköz végrehajtását, a következő történik:

A DatabricksFunctionClient rendszer kérést küld a Unity Catalognak a függvénydefiníció lekéréséhez, ha a definíciót nem helyileg gyorsítótárazták.
A DatabricksFunctionClient függvénydefiníció kinyerése és a paraméternevek és -típusok ellenőrzése.
A DatabricksFunctionClient végrehajtást UDF-ként küldi el a kiszolgáló nélküli általános számításnak.

Helyi fejlesztési mód

A helyi mód egy helyi alfolyamatban hajtja végre a Python-függvényeket a kiszolgáló nélküli általános számítás kérése helyett. Ez lehetővé teszi az eszközhívások hatékonyabb hibaelhárítását helyi veremkövetések biztosításával. Python Unity Catalog-függvények fejlesztésére és hibakeresésére tervezték.

Amikor az ügynök azt kéri, hogy helyi módban futtasson egy eszközt, a DatabricksFunctionClient következőket hajtja végre:

Kérést küld a Unity Catalognak a függvénydefiníció lekéréséhez, ha a definíciót nem helyileg gyorsítótárazták.
A rendszer kinyeri a Python hívható definícióját, helyileg gyorsítótárazza a hívhatót, és ellenőrzi a paraméterneveket és -típusokat.
Meghívja a meghívhatót a megadott paraméterekkel egy korlátozott alfolyamatban, időtúllépés elleni védelemmel.

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

A módban való "local" futtatás a következő funkciókat biztosítja:

CPU-időkorlát: Korlátozza a teljes PROCESSZOR-futtatókörnyezetet a hívható végrehajtáshoz, hogy megakadályozza a túlzott számítási terhelést.

A CPU-időkorlát a tényleges processzorhasználaton alapul, nem pedig a falióra időtartamán. A rendszerütemezés és az egyidejű folyamatok miatt a processzoridő a valós helyzetekben meghaladhatja a falióra idejét.
Memóriakorlát: Korlátozza a folyamathoz lefoglalt virtuális memóriát.
Időtúllépés elleni védelem: A függvények futtatásához a falióra teljes időtúllépését kényszeríti ki.

Ezeket a korlátokat környezeti változókkal szabhatja testre (további információ).

Helyi mód korlátozásai

Csak Python-függvények: Az SQL-alapú függvények helyi módban nem támogatottak.
A nem megbízható kód biztonsági szempontjai: Bár a helyi mód függvényeket futtat egy folyamatelkülönítési alfolyamatban, az AI-rendszerek által létrehozott tetszőleges kód végrehajtásakor biztonsági kockázat merül fel. Ez elsősorban akkor jelent problémát, ha a függvények dinamikusan generált Python-kódot hajtanak végre, amelyeket nem vizsgáltak át.
Erőforrástár verzióbeli eltérései: A tár verziói eltérőek lehetnek a kiszolgáló nélküli és a helyi végrehajtási környezetek között, ami eltérő működéshez vezethet.

Környezeti változók

Konfigurálja, hogyan futnak a függvények a DatabricksFunctionClient következő környezeti változók használatával:

Környezeti változó	Alapértelmezett érték	Leírás
`EXECUTOR_MAX_CPU_TIME_LIMIT`	`10` másodperc	Maximális engedélyezett PROCESSZOR-végrehajtási idő (csak helyi mód esetén).
`EXECUTOR_MAX_MEMORY_LIMIT`	`100` MB	A folyamat számára engedélyezett virtuális memória maximális lefoglalása (csak helyi mód esetén).
`EXECUTOR_TIMEOUT`	`20` másodperc	A fali óra maximális időtartama (csak helyi mód esetén).
`UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS`	`5`	A munkamenet kliens frissítésének újbóli próbálkozásainak maximális száma token lejárata esetén.
`UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT`	`100`	A függvények kiszolgáló nélküli számítással való futtatásakor visszatérítendő sorok maximális számát határozza meg és `databricks-connect`.

Következő lépések

Unity Catalog-eszközök hozzáadása az ügynökökhöz programozott módon. Lásd ResponsesAgent példákat.
Unity Catalog-eszközök hozzáadása ügynökökhöz az AI Playground felhasználói felületén. Tekintse meg a prototípus eszközöket meghívó ügynököket az AI játszótéren.
A Unity Catalog-függvények kezelése a függvényügyfél használatával. Lásd a Unity Catalog dokumentációját – Funkciókliens

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-08-15