Unity Kataloğu işlevlerini kullanarak aracı araçları oluşturma

Özel mantık yürüten ve LLM'lerin özelliklerini dil oluşturmanın ötesine genişleten belirli görevleri gerçekleştiren aracı araçları oluşturmak için Unity Kataloğu işlevlerini kullanın.

Unity Kataloğu işlevlerinin ve MCP sunucularının ne zaman kullanılacağı

Databricks, sorgu önceden bilindiğinde ve aracı parametreleri sağladığında Unity Kataloğu işlevlerinin yapılandırılmış veri alma araçları için özel olarak aracı araçları olarak kullanılmasını önerir. Bkz . Aracıları yapılandırılmış verilere bağlama.

Diğer kullanım örneklerinin çoğunda Databricks daha hızlı yürütme, kullanıcı başına kimlik doğrulaması desteği ve ek esneklik için MCP sunucularını önerir veya mantığı doğrudan aracı kodunda tanımlar.

Requirements

Unity Kataloğu işlevlerini aracı araçları olarak oluşturmak ve kullanmak için aşağıdakilere ihtiyacınız vardır:

• Databricks Runtime: Databricks Runtime 15.0 ve üzerini kullanma
• Python sürümü: Python 3.10 veya üzerini yükleme

Unity Kataloğu işlevlerini çalıştırmak için:

• Unity Kataloğu işlevlerini üretimde aracı araçları olarak yürütmek için çalışma alanınızda sunucusuz işlem etkinleştirilmelidir. Bkz. Sunucusuz işlem gereksinimleri.
  • Python işlevleri için yerel mod yürütme, sunucusuz genel işlemin çalıştırılmasını gerektirmez, ancak yerel mod yalnızca geliştirme ve test amacıyla tasarlanmıştır.

Unity Kataloğu işlevleri oluşturmak için:

• Databricks Çalışma Alanı İstemcisi veya SQL gövde deyimlerini kullanarak işlev oluşturmak için çalışma alanınızda sunucusuz genel işlem etkinleştirilmelidir.
  • Python işlevleri sunucusuz işlem olmadan oluşturulabilir.

Unity Kataloğu işlev aracı oluşturma

Aşağıdaki adımlarda Unity Kataloğu işlevini oluşturma ve test etme adımları gösterilmektedir. Databricks not defterinde aşağıdaki kodu çalıştırın.

Tip

Genie Code'a (Aracı modu) bunu sizin için gerçekleştirmesini söyleyin:

Create a Unity Catalog Python function that an AI agent can use as a tool. It should take two floating point numbers and return their sum, with type hints and a Google-style docstring. Register it using the Databricks Function Client, then test calling it.

Bağımlılıkları yükleme

Unity Kataloğu AI paketlerini [databricks] extra ile yükleyin.

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

dbutils.library.restartPython()

Databricks İşlev İstemcisi'ni başlatma

Databricks'te Unity Kataloğu işlevlerini oluşturmak, yönetmek ve çalıştırmak için özel bir arabirim olan Databricks İşlev İstemcisi'ni başlatın.

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

Aracın mantığını tanımla

Unity Kataloğu araçları, aslında Unity Kataloğu kullanıcı tanımlı işlevlerdir (UDF'ler). Unity Kataloğu aracını tanımlarken, Unity Kataloğu'nda bir işlev kaydedersiniz. Unity Kataloğu UDF'leri hakkında daha fazla bilgi edinmek için bkz. Unity Kataloğu'nda SQL ve Python kullanıcı tanımlı işlevler (UDF' ler).

Uyarı

Aracı aracında rastgele kod yürütmek, aracının erişimi olan hassas veya özel bilgileri ifşa edebilir. Müşteriler yalnızca güvenilen kodu çalıştırmak ve verilere istenmeyen erişimi önlemek için korumaları ve uygun izinleri yapılandırmakla sorumludur.

İki API'nin birini kullanarak Unity Kataloğu işlevleri oluşturabilirsiniz:

• create_python_function Python çağrılabilen bir değeri kabul eder.
• create_function bir SQL gövdesi oluşturma işlev deyimini kabul eder. Bkz. Python işlevleri oluşturma.

İşlevi create_python_function oluşturmak için API'yi kullanın.

Unity Kataloğu işlevleri veri modeli için çağrılabilen bir Python yapmak için işlevinizin aşağıdaki gereksinimleri karşılaması gerekir:

• Tür ipuçları: İşlev imzası geçerli Python türü ipuçlarını tanımlamalıdır. Hem adlandırılmış bağımsız değişkenlerin hem de dönüş değerinin türleri tanımlanmış olmalıdır.
• Değişken bağımsız değişkenlerini kullanmayın: *args ve **kwargs gibi değişken bağımsız değişkenleri desteklenmez. Tüm bağımsız değişkenler açıkça tanımlanmalıdır.
• Tür uyumluluğu: SQL'de tüm Python türleri desteklenmez. Bkz. Spark Tarafından Desteklenen Veri Türleri.
• Açıklayıcı docstring'ler: Unity Kataloğu araç seti işlevleri, docstring'inizden önemli bilgileri okur, ayrıştırır ve çıkarır.
  • Docstrings, Google docstring söz dizimine göre biçimlendirilmelidir.
  • LLM'nin işlevin nasıl ve ne zaman kullanılacağını anlamasına yardımcı olmak için işleviniz ve bağımsız değişkenleri için net açıklamalar yazın.
• Bağımlılıkların içe aktarılması: Kitaplıklar işlevin içinde içe aktarılmalıdır. Araç çalıştırıldığında, işlevin dışındaki dışa aktarımlar çözülemez.

Aşağıdaki kod parçacığı, Python çağrılabilen create_python_function öğesini kaydetmek için add_numbers öğesini kullanır.

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
)

İşlevi test et.

İşlevinizin beklendiği gibi çalışıp çalışmadığını denetlemek için işlevinizi test edin. API'de işlevi çalıştırmak için execute_function tam işlev adını belirtin.

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'

Aracınıza Unity Kataloğu işlevleri ekleme

Unity Kataloğu işlevinizi oluşturup test ettikten sonra aracınıza eklemek için aşağıdaki yaklaşımlardan birini seçin.

MCP kullanma (önerilen)

MCP kullanma (önerilen)

Databricks, aracınıza Unity Kataloğu işlevleri eklemek için MCP sunucularının kullanılmasını önerir. MCP yaklaşımı, otomatik araç bulma ve yerleşik kimlik doğrulama desteği ile daha basit bir tümleştirme sağlar.

Unity Kataloğu işlevleri için yönetilen MCP URL'si: https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}. İsteğe bağlı olarak, /{function_name} ekleyerek belirli bir işlev belirtebilirsiniz.

Aşağıdaki örneklerde, aracınızı MCP aracılığıyla Unity Kataloğu işlevlerine nasıl bağlayacağınız gösterilmektedir. <catalog> ve <schema> öğelerini işlevlerinizin konumuyla değiştirin.

OpenAI Aracıları SDK'sı (Uygulamalar)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()

async with McpServer.from_uc_function(
    catalog="<catalog>",
    schema="<schema>",
    workspace_client=workspace_client,
    name="uc-functions",
) as uc_server:
    agent = Agent(
        name="Tool-using agent",
        instructions="You are a helpful assistant. Use the available tools to answer questions.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[uc_server],
    )
    result = await Runner.run(agent, "Look up customer info for Acme Corp")
    print(result.final_output)

Unity Kataloğu işlevine databricks.yml uygulamasında erişim izni verin.

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_uc_function'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<function-name>'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

LangGraph (Uygulamalar)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="uc-functions",
        url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Look up customer info for Acme Corp"}]}
    )
    print(result["messages"][-1].content)

Unity Kataloğu işlevine databricks.yml uygulamasında erişim izni verin.

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_uc_function'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<function-name>'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

Model Hizmeti

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

# Connect to the UC functions MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/functions/<catalog>/<schema>",
    workspace_client=workspace_client,
)

# List available tools
tools = mcp_client.list_tools()

# Log the agent with the required resources for deployment
mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Aracıyı dağıtmak için bkz. Yapay zeka uygulamaları için aracı dağıtma (Model Sunma). MCP kaynaklarıyla aracıların günlüğe kaydedilmesi hakkında ayrıntılı bilgi için bkz. Azure Databricks tarafından yönetilen MCP sunucuları.

UCFunctionToolkit kullanma

UCFunctionToolkit kullanma

Bu örnekte LangChain kullanılır, ancak diğer kitaplıklara benzer bir yaklaşım uygulanabilir. Bkz. Unity Catalog araç entegrasyonu.

Ek bağımlılıkları yükleme

UCFunctionToolkit için LangChain tümleştirme paketlerini yükleyin.

%pip install unitycatalog-langchain[databricks]==0.2.0

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

dbutils.library.restartPython()

UCFunctionToolKit kullanarak işlevi sarmalayın

İşlevi, aracı yazma kitaplıkları tarafından erişilebilir hale getirmek için UCFunctionToolkit kullanarak sarmalayın. Araç seti, farklı yapay zeka kitaplıklarında tutarlılık sağlar ve almacılar için otomatik izleme gibi yararlı özellikler ekler.

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

Bir aracı ajan içinde kullanın

Aracı tools özelliğini UCFunctionToolkit kullanarak bir LangChain aracısına ekleyin.

Note

Bu örnekte LangChain kullanılır. Ancak Unity Kataloğu araçlarını LlamaIndex, OpenAI, Anthropic ve daha fazlası gibi diğer çerçevelerle tümleştirebilirsiniz. Bkz. Unity Catalog araç entegrasyonu.

Bu örnek basitlik için LangChain AgentExecutor API'sini kullanarak basit bir aracı yazar. Üretim iş yükleri için, Aracı yazma bölümünde görülen aracı yazma iş akışını kullanın ve bunu Databricks Uygulamalarına dağıtın.

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

Araç çağırmayı net belgelerle iyileştirin

İyi belgeler, aracılarınızın her aracın ne zaman ve nasıl kullanılacağını bilmesine yardımcı olur. Araçlarınızı belgeleme için şu en iyi yöntemleri izleyin:

• Unity Kataloğu işlevlerinde, araç işlevselliğini ve parametrelerini açıklamak için yan tümcesini COMMENT kullanın.
• Beklenen girişleri ve çıkışları açıkça tanımlayın.
• Aracıların ve insanların kullanımını kolaylaştırmak için anlamlı açıklamalar yazın.

Örnek: Etkili araç belgeleri

Aşağıdaki örnekte yapılandırılmış bir tabloyu sorgulayan bir aracın net COMMENT dizeleri gösterilmektedir.

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;

Örnek: Etkisiz araç belgeleri

Aşağıdaki örnekte önemli ayrıntılar eksiktir ve aracıların aracı etkili bir şekilde kullanmasını zorlaştırır:

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;

Sunucusuz veya yerel modu kullanarak işlevleri çalıştırma

Bir yapay zeka hizmeti bir araç çağrısının gerekli olduğunu belirlediğinde, entegrasyon paketleri (UCFunctionToolkit örnekleri) DatabricksFunctionClient.execute_function API'sini çalıştırır.

Çağrı, execute_function işlevleri iki yürütme modunda çalıştırabilir: sunucusuz veya yerel. Bu mod işlevi hangi kaynağın çalıştırdığını belirler.

Üretim için sunucusuz mod

Sunucusuz mod, Unity Kataloğu aracı araçları olarak yürütülürken üretim kullanım örnekleri için varsayılan ve önerilen seçenektir. Bu mod, işlevleri uzaktan yürütmek için sunucusuz genel işlem (Spark Connect sunucusuz) kullanır ve Lakeguard aracınızın işleminin güvenli kalmasını ve rastgele kodu yerel olarak çalıştırma risklerinden uzak kalmasını sağlar.

Note

Ajan araçları olarak yürütülen Unity Catalog işlevleri, sunucusuz SQL veri ambarları değil, genel amaçlı sunucusuz işlem (Spark Connect serverless) gerektirir. Sunucusuz genel işlem olmadan araçları çalıştırma girişimleri PERMISSION_DENIED: Cannot access Spark Connect gibi hatalara yol açar.

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

Aracınız sunucusuz modda bir araç yürütme isteğinde bulunursa, aşağıdakiler gerçekleşir:

1. , DatabricksFunctionClient tanım yerel olarak önbelleğe alınmadıysa işlev tanımını almak için Unity Kataloğu'na bir istek gönderir.
2. işlevi DatabricksFunctionClient tanımını ayıklar ve parametre adlarını ve türlerini doğrular.
3. , DatabricksFunctionClient yürütmeyi sunucusuz genel işlem için UDF olarak gönderir.

Geliştirme için yerel mod

Yerel mod, sunucusuz genel işleme istekte bulunmak yerine Python işlevlerini yerel bir alt işlemde yürütür. Bu, yerel yığın izlemeleri sağlayarak araç çağrılarıyla ilgili sorunları daha etkili bir şekilde gidermenizi sağlar. Python Unity Kataloğu işlevlerini geliştirmek ve hatalarını ayıklamak için tasarlanmıştır.

Temsilciniz yerel modda bir aracın çalıştırılmasını DatabricksFunctionClient istediğinde aşağıdakileri yapar:

1. Tanım yerel olarak önbelleğe alınmadıysa işlev tanımını almak için Unity Kataloğu'na bir istek gönderir.
2. çağrılabilen Python tanımını ayıklar, çağrılabileni yerel olarak önbelleğe alır ve parametre adlarını ve türlerini doğrular.
3. Zaman aşımı korumasına sahip kısıtlı bir alt işlemde belirtilen parametrelerle çağrılabilir öğesini çağırır.

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

Modda "local" çalıştırmak aşağıdaki özellikleri sağlar:

• CPU süre sınırı: Aşırı hesaplama yüklerini önlemek için çağrılabilen yürütme için toplam CPU çalışma zamanını kısıtlar.

  CPU zaman sınırı, duvar saati zamanına değil gerçek CPU kullanımına bağlıdır. Sistem zamanlaması ve eşzamanlı işlemler nedeniyle GERÇEK dünya senaryolarında CPU süresi duvar saati süresini aşabilir.

• Bellek sınırı: İşleme ayrılan sanal belleği kısıtlar.

• Zaman aşımı koruması: Çalışan işlevler için toplam duvar saati zaman aşımını zorlar.

Ortam değişkenlerini kullanarak bu sınırları özelleştirin (daha fazla bilgi edinin).

Yerel mod sınırlamaları

• Yalnızca Python işlevleri: SQL tabanlı işlevler yerel modda desteklenmez.
• Güvenilmeyen kod için güvenlikle ilgili dikkat edilmesi gerekenler: Yerel mod işlevleri işlem yalıtımı için bir alt işlemde çalıştırırken, yapay zeka sistemleri tarafından oluşturulan rastgele kod yürütülürken olası bir güvenlik riski vardır. İşlevlerin dinamik olarak oluşturulan ve gözden geçirilmemiş Python kodu yürütmesi öncelikli olarak bir sorundur.
• Kitaplık sürümü farklılıkları: Kitaplık sürümleri sunucusuz ve yerel yürütme ortamları arasında farklılık gösterebilir ve bu da farklı işlev davranışlarına yol açabilir.

Ortam değişkenleri

aşağıdaki ortam değişkenlerini kullanarak işlevlerin içinde DatabricksFunctionClient nasıl çalıştırılacaklarını yapılandırın:

Ortam değişkeni	Varsayılan değer	Tanım
EXECUTOR_MAX_CPU_TIME_LIMIT	10 Saniye	İzin verilen en fazla CPU yürütme süresi (yalnızca yerel mod).
EXECUTOR_MAX_MEMORY_LIMIT	100 MB	İşlem için izin verilen en yüksek sanal bellek ayırma (yalnızca yerel mod).
EXECUTOR_TIMEOUT	20 Saniye	Toplam duvar saati süresi üst sınırı (yalnızca yerel mod).
UCAI_DATABRICKS_SESSION_RETRY_MAX_ATTEMPTS	5	Erişim anahtarının süresinin dolması durumunda oturum istemcisini yenilemeye yönelik yeniden deneme girişimlerinin maksimum sayısı.
UCAI_DATABRICKS_SERVERLESS_EXECUTION_RESULT_ROW_LIMIT	100	Fonksiyonları sunucusuz işlem ve databricks-connect kullanarak çalıştırırken döndürülecek maksimum satır sayısı.

(eski) ile http_request dış API'leri çağırma

SQL tabanlı araç tanımlarından harici servisleri çağırmak için wrap yapan bir Unity Kataloğu fonksiyonu http_request() oluşturabilirsiniz. Bu yaklaşım desteklenmeye devam ediyor ancak yeni entegrasyonlar için artık önerilmiyor. Kılavuz için, SQL örneği ve bağlantı türü sınırlamaları dahil, HTTP bağlantılı Unity Catalog fonksiyon araçlarına bakınız.

Örnek not defterleri

Aşağıdaki not defterleri Unity Kataloğu işlevlerini kullanarak dış hizmetlere bağlanan aracı araçları oluşturmayı gösterir.

Slack mesajlaşma aracı

Dizüstü bilgisayar al

Microsoft Graph API aracı

Dizüstü bilgisayar al

Azure AI Arama aracı

Dizüstü bilgisayar al

Sonraki Adımlar

• Aracılara program aracılığıyla Unity Kataloğu araçları ekleyin. Bkz. Bir aracı yazma ve Databricks Uygulamalarında dağıtma.

• AI Playground kullanıcı arabirimini kullanarak aracılara Unity Kataloğu araçları ekleyin. Bkz. Başlarken: Kod yazmadan LLM'leri sorgulama ve ajan prototipleri oluşturma.

• Unity Kataloğu işlevlerini İşlev İstemcisi'ni kullanarak yönetin. Unity Kataloğu belgelerine bakın - İşlev istemcisi

• Aracıları dış hizmetlere bağlamaya yönelik tüm yaklaşımlara genel bakış için MCP Hizmetleri ile aracıları üçüncü taraf araçlara bağlayın.