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. Unity Kataloğunu diğer yapay zeka çerçeveleriyle birlikte kullanın bölümüne bakınız.

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. Unity Kataloğunu diğer yapay zeka çerçeveleriyle birlikte kullanın bölümüne bakınız.

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

Unity Kataloğu araçlarını diğer yapay zeka çerçeveleriyle birlikte kullanın

LangChain'in (yukarıda gösterilen) ötesinde, Unity Catalog ajanı araçları LlamaIndex, OpenAI ve Anthropic gibi diğer popüler yapay zeka kütüphaneleriyle çalışır. Bu entegrasyonlar, Unity Kataloğu araç yönetişimini üçüncü taraf ajan yazarlık çerçevelerinin yetenekleriyle birleştirir. Örneğin, OpenAI veya Anthropic entegrasyonlarında, işlevler uygulama sırasında doğrudan yapay zeka modeli tarafından çağrılır.

Bir Unity Kataloğu aracı oluşturmak ve bu çerçeveyle kullanmak için aşağıdaki sekmelerde çerçevenizi seçin. Kodu bir Azure Databricks not defterinde veya Python betiğinde çalıştırın.

LlamaIndex

SQL ve Python işlevlerini LlamaIndex iş akışlarında araç olarak tümleştirmek için Azure Databricks Unity Kataloğu'nu kullanın. Bu tümleştirme, Unity Kataloğu idaresini LlamaIndex'in LLM'ler için büyük veri kümelerini dizinleme ve sorgulama özellikleriyle birleştirir.

1. LlamaIndex için Databricks Unity Kataloğu tümleştirme paketini yükleyin.

   %pip install unitycatalog-llamaindex[databricks]
   dbutils.library.restartPython()
   

2. Unity Kataloğu işlevleri istemcisinin bir örneğini oluşturun.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Python'da yazılmış bir Unity Kataloğu işlevi oluşturun.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.code_function"
   
   def code_function(code: str) -> str:
     """
     Runs Python code.
   
     Args:
       code (str): The Python code to run.
     Returns:
       str: The result of running the Python code.
     """
     import sys
     from io import StringIO
     stdout = StringIO()
     sys.stdout = stdout
     exec(code)
     return stdout.getvalue()
   
   client.create_python_function(
     func=code_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Unity Kataloğu işlevinin bir örneğini araç seti olarak oluşturun ve aracın düzgün davrandığını doğrulamak için bunu çalıştırın.

   from unitycatalog.ai.llama_index.toolkit import UCFunctionToolkit
   import mlflow
   
   # Enable traces
   mlflow.llama_index.autolog()
   
   # Create a UCFunctionToolkit that includes the UC function
   toolkit = UCFunctionToolkit(function_names=[func_name])
   
   # Fetch the tools stored in the toolkit
   tools = toolkit.tools
   python_exec_tool = tools[0]
   
   # Run the tool directly
   result = python_exec_tool.call(code="print(1 + 1)")
   print(result)  # Outputs: {"format": "SCALAR", "value": "2\n"}
   

5. Unity Kataloğu işlevini bir LlamaIndex araç koleksiyonunun parçası olarak tanımlayarak bir LlamaIndex ReActAgent'da aracı kullanın. Ardından LlamaIndex araç koleksiyonunu çağırarak aracının düzgün davrandığını doğrulayın.

   from llama_index.llms.openai import OpenAI
   from llama_index.core.agent import ReActAgent
   
   llm = OpenAI()
   
   agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)
   
   agent.chat("Please run the following python code: `print(1 + 1)`")
   

OpenAI

SQL ve Python işlevlerini OpenAI iş akışlarında araç olarak tümleştirmek için Azure Databricks Unity Kataloğu'nu kullanın. Bu tümleştirme, güçlü yapay zeka uygulamaları oluşturmak için Unity Kataloğu idaresini OpenAI ile birleştirir.

1. OpenAI için Databricks Unity Kataloğu tümleştirme paketini yükleyin.

   %pip install unitycatalog-openai[databricks]
   %pip install mlflow -U
   dbutils.library.restartPython()
   

2. Unity Kataloğu işlevleri istemcisinin bir örneğini oluşturun.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Python'da yazılmış bir Unity Kataloğu işlevi oluşturun.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.code_function"
   
   def code_function(code: str) -> str:
     """
     Runs Python code.
   
     Args:
       code (str): The python code to run.
     Returns:
       str: The result of running the Python code.
     """
     import sys
     from io import StringIO
     stdout = StringIO()
     sys.stdout = stdout
     exec(code)
     return stdout.getvalue()
   
   client.create_python_function(
     func=code_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Unity Kataloğu işlevinin bir örneğini araç seti olarak oluşturun ve işlevi çalıştırarak aracın düzgün davrandığını doğrulayın.

   from unitycatalog.ai.openai.toolkit import UCFunctionToolkit
   import mlflow
   
   # Enable tracing
   mlflow.openai.autolog()
   
   # Create a UCFunctionToolkit that includes the UC function
   toolkit = UCFunctionToolkit(function_names=[func_name])
   
   # Fetch the tools stored in the toolkit
   tools = toolkit.tools
   client.execute_function = tools[0]
   

5. İsteği araçlarla birlikte OpenAI modeline gönderin.

   import openai
   
   messages = [
     {
       "role": "system",
       "content": "You are a helpful customer support assistant. Use the supplied tools to assist the user.",
     },
     {"role": "user", "content": "What is the result of 2**10?"},
   ]
   response = openai.chat.completions.create(
     model="gpt-4o-mini",
     messages=messages,
     tools=tools,
   )
   # check the model response
   print(response)
   

6. OpenAI bir yanıt döndürdüğünde, Yanıt yanıtını OpenAI'ye geri oluşturmak için Unity Kataloğu işlev çağrısını çağırın.

   import json
   
   # OpenAI sends only a single request per tool call
   tool_call = response.choices[0].message.tool_calls[0]
   # Extract arguments that the Unity Catalog function needs to run
   arguments = json.loads(tool_call.function.arguments)
   
   # Run the function based on the arguments
   result = client.execute_function(func_name, arguments)
   print(result.value)
   

7. Yanıt döndürüldükten sonra OpenAI'ye yapılan sonraki çağrılar için yanıt yükünü oluşturabilirsiniz.

   # Create a message containing the result of the function call
   function_call_result_message = {
     "role": "tool",
     "content": json.dumps({"content": result.value}),
     "tool_call_id": tool_call.id,
   }
   assistant_message = response.choices[0].message.to_dict()
   completion_payload = {
     "model": "gpt-4o-mini",
     "messages": [*messages, assistant_message, function_call_result_message],
   }
   
   # Generate final response
   openai.chat.completions.create(
     model=completion_payload["model"], messages=completion_payload["messages"]
   )
   

Hizmetler

Araç yanıtını oluşturma işlemini basitleştirmek için, ucai-openai paketi OpenAI ChatCompletion yanıt iletilerini yanıt oluşturmada kullanılabilecek hale getiren bir araç sağlar.

from unitycatalog.ai.openai.utils import generate_tool_call_messages

messages = generate_tool_call_messages(response=response, client=client)
print(messages)

Note

Yanıt birden çok seçenekli girdi içeriyorsa, generate_tool_call_messages çağırırken choice_index bağımsız değişkenini, hangi seçim girişinin kullanılacağını seçmek için geçirebilirsiniz. Şu anda çoktan seçmeli girişleri işleme desteği yoktur.

Anthropic

SQL ve Python işlevlerini Anthropic SDK LLM çağrılarında araç olarak tümleştirmek için Azure Databricks Unity Kataloğu'nu kullanın. Bu tümleştirme, güçlü yapay zeka uygulamaları oluşturmak için Unity Kataloğu'nun idaresini Anthropic modellerle birleştirir.

Note

Anthropic tümleştirmesi için Databricks Runtime 15.0 ve üzeri gerekir.

1. Antropik için Databricks Unity Kataloğu tümleştirme paketini yükleyin.

   %pip install unitycatalog-anthropic[databricks]
   dbutils.library.restartPython()
   

2. Unity Kataloğu işlevleri istemcisinin bir örneğini oluşturun.

   from unitycatalog.ai.core.base import get_uc_function_client
   
   client = get_uc_function_client()
   

3. Python'da yazılmış bir Unity Kataloğu işlevi oluşturun.

   CATALOG = "your_catalog"
   SCHEMA = "your_schema"
   
   func_name = f"{CATALOG}.{SCHEMA}.weather_function"
   
   def weather_function(location: str) -> str:
     """
     Fetches the current weather from a given location in degrees Celsius.
   
     Args:
       location (str): The location to fetch the current weather from.
     Returns:
       str: The current temperature for the location provided in Celsius.
     """
     return f"The current temperature for {location} is 24.5 celsius"
   
   client.create_python_function(
     func=weather_function,
     catalog=CATALOG,
     schema=SCHEMA,
     replace=True
   )
   

4. Unity Kataloğu işlevinin bir örneğini araç seti olarak oluşturun.

   from unitycatalog.ai.anthropic.toolkit import UCFunctionToolkit
   
   # Create an instance of the toolkit
   toolkit = UCFunctionToolkit(function_names=[func_name], client=client)
   

5. Antropik'te bir araç çağrısı kullanın.

   import anthropic
   
   # Initialize the Anthropic client with your API key
   anthropic_client = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")
   
   # User's question
   question = [{"role": "user", "content": "What's the weather in New York City?"}]
   
   # Make the initial call to Anthropic
   response = anthropic_client.messages.create(
     model="claude-3-5-sonnet-20240620",  # Specify the model
     max_tokens=1024,  # Use 'max_tokens' instead of 'max_tokens_to_sample'
     tools=toolkit.tools,
     messages=question  # Provide the conversation history
   )
   
   # Print the response content
   print(response)
   

6. Bir araç yanıtı oluşturun. Claude modelinden gelen yanıt, bir aracın çağrılması gerekiyorsa bir araç isteği meta veri bloğu içerir.

   from unitycatalog.ai.anthropic.utils import generate_tool_call_messages
   
   # Call the UC function and construct the required formatted response
   tool_messages = generate_tool_call_messages(
     response=response,
     client=client,
     conversation_history=question
   )
   
   # Continue the conversation with Anthropic
   tool_response = anthropic_client.messages.create(
     model="claude-3-5-sonnet-20240620",
     max_tokens=1024,
     tools=toolkit.tools,
     messages=tool_messages,
   )
   
   print(tool_response)
   

Paket, unitycatalog.ai-anthropic Unity Kataloğu işlevine yapılan çağrının ayrıştırılması ve işlenmesini basitleştirmek için bir ileti işleyici yardımcı programı içerir. Yardımcı programı aşağıdakileri yapar:

1. Araç çağırma gereksinimlerini algılar.
2. Sorgudan araç çağrı bilgilerini ayıklar.
3. Unity Kataloğu işlevine yapılan çağrıyı gerçekleştirir.
4. Unity Kataloğu işlevinden yanıtı ayrıştırıyor.
5. Claude ile konuşmaya devam etmek için bir sonraki ileti biçimini üretin.

Note

Konuşma geçmişinin tamamı conversation_history bağımsız değişkeni olarak generate_tool_call_messages API'sine sağlanmalıdır. Claude modelleri, konuşmanın başlatılmasını (özgün kullanıcı girişi sorusu) ve sonraki tüm LLM tarafından oluşturulan yanıtları ve çok aşamalı araç çağrı sonuçlarını gerektirir.

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ı içinden harici hizmetleri çağırmak için http_request() öğesini sarmalayan bir Unity Catalog işlevi oluşturabilirsiniz. Bu yaklaşım desteklenmeye devam ediyor ancak yeni entegrasyonlar için artık önerilmiyor. SQL örneği ve bağlantı türü sınırlamaları dahil olmak üzere rehber için Unity Kataloğunda Wrap http_request() fonksiyonuna 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

• Ajanları MCP Services ile araçlara bağlayarak ajanların dış hizmetlere bağlanmasına yönelik tüm yaklaşımların genel bir görünümünü elde edin.