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

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

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.

Gereksinimler

Unity Kataloğu işlevlerini yapay zeka aracısı 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 version: Python 3.10 veya üzerini yükleyin

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

Unity Kataloğu işlevlerini üretim ortamında yapay zeka aracısı 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 Local modu 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.

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 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ılabilirini 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:

Type 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.
Type 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ılabilir create_python_function kaydetmek için add_numbers 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. Oluşturucu yapay zeka uygulamaları (Model Sunma) için aracı dağıtma. MCP kaynakları ile günlük alma hakkında ayrıntılı bilgi için bkz. Databricks tarafından yönetilen MCP sunucularını kullanımı.

UCFunctionToolkit kullanma

UCFunctionToolkit kullanma

Bu örnekte LangChain kullanılır, ancak diğer kitaplıklara benzer bir yaklaşım uygulanabilir. Bkz. Unity Kataloğu araçlarını üçüncü taraf üretici yapay zeka çerçeveleriyle tümleştirme.

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

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

%pip install unitycatalog-langchain[databricks]

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

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ı nesil 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.

Uyarı

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 Kataloğu araçlarını üçüncü taraf üretici yapay zeka çerçeveleriyle tümleştirme.

Bu örnek basitlik için LangChain AgentExecutor API'sini kullanarak basit bir aracı yazar. Üretim iş yükleri için Yapay zeka aracısı 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 üretken yapay zeka hizmeti bir araç çağrısı gerektiğini belirlediğinde, bütünleşik paketler (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 işlevlerini yapay zeka aracısı araçları olarak yürütü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.

Uyarı

Yapay zeka aracısı araçları olarak yürütülen Unity Kataloğu işlevleri sunucusuz SQL ambarları değil sunucusuz genel işlem (Spark Connect sunucusuz) 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:

, 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.
işlevi DatabricksFunctionClient tanımını ayıklar ve parametre adlarını ve türlerini doğrular.
, 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şlevleri 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. Unity Kataloğu işlevlerini geliştirmek ve hata ayıklamak Python için tasarlanmıştır.

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

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.
ç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.
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	Açıklama
`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ı.

Örnek not defterleri

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

Sonraki Adımlar

Aracılara program aracılığıyla Unity Kataloğu araçları ekleyin. Bkz. Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma.
AI Playground kullanıcı arabirimini kullanarak aracılara Unity Kataloğu araçları ekleyin. Bkz: Koda gerek kalmadan LLM'leri sorgulama ve yapay zeka aracılarının prototiplerini 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 aracıları dış hizmetlere bağlama.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-11

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

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

Gereksinimler

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

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

Databricks İşlev İstemcisi'ni başlatma

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

İşlevi test et.

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

MCP kullanma (önerilen)

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

LangGraph (Uygulamalar)

Model Hizmeti

UCFunctionToolkit kullanma

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

UCFunctionToolKit kullanarak işlevi sarmalayın

Bir aracı ajan içinde kullanın

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

Örnek: Etkili araç belgeleri

Örnek: Etkisiz araç belgeleri

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

Üretim için sunucusuz mod

Geliştirme için yerel mod

Yerel mod sınırlamaları

Ortam değişkenleri

Örnek not defterleri

Slack mesajlaşma aracı

Microsoft Graph API aracı

Azure AI Arama aracı

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar