Pular para o conteúdo principal
Última atualização em

Metaparâmetros para Databricks gerenciar servidores MCP

info

Visualização

Este recurso está em Pré-visualização Pública.

Ao criar agentes de AI que usam servidores MCP gerenciados pelo Databricks, use o parâmetro _meta para configurar o comportamento da ferramenta, como limites de resultados, filtros de pesquisa ou seleção de SQL warehouse. Essa abordagem permite que você predefina a configuração, mantendo as queries flexíveis para que seu agente as gere dinamicamente.

O parâmetro _meta faz parte da especificação oficial do MCP.

Argumentos de chamada de ferramenta vs. parâmetros _meta​

Os servidores Databricks gerenciam MCP e lidam com parâmetros de duas maneiras:

  • Argumentos de chamada da ferramenta : Parâmetros que um LLM normalmente gera dinamicamente com base na entrada do usuário.
  • _meta parâmetros : Parâmetros de configuração que podem ser predefinidos no código do agente para definir o comportamento de forma determinística.

Parâmetros do servidor Databricks SQL MCP _meta​

O servidor MCP do Databricks SQL oferece suporte aos seguintes parâmetros _meta:

Nome do parâmetro

Tipo

Descrição

warehouse_id

str

O ID do SQL warehouse a ser usado para executar as consultas.

Exemplo: "a1b2c3d4e5f67890"

Caso não seja especificado, o sistema seleciona automaticamente um armazém com base nos recursos e permissões.

Exemplo: especificar um SQL warehouse para consultas Databricks SQL​

Este exemplo mostra como usar o parâmetro warehouse_id _meta para especificar qual SQL warehouse executa consultas do servidor MCP do Databricks SQL usando o SDK MCP Python oficial.

Neste cenário, você quer:

  • Utilize um SQL warehouse específico para a execução de consultas em vez de deixar o sistema selecionar um automaticamente.
  • Verifique o desempenho consistente roteando queries para um warehouse dedicado

Para executar este exemplo, configure seu ambiente Python para gerenciar o desenvolvimento do MCP:

Expanda para ver o exemplo de código.

Para encontrar o ID do seu SQL warehouse , consulte Conectar-se a um SQL warehouse.

Python
# Import required libraries for MCP client and Databricks authentication
import asyncio
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult

async def run_dbsql_tool_call_with_meta():
    # Initialize Databricks workspace client for authentication
    workspace_client = WorkspaceClient()

    # Construct the MCP server URL for DBSQL
    # Replace <workspace-hostname> with your workspace hostname
    mcp_server_url = "https://<workspace-hostname>/api/2.0/mcp/sql"

    # Establish connection to the MCP server with OAuth authentication
    async with streamablehttp_client(
        url=mcp_server_url,
        auth=DatabricksOAuthClientProvider(workspace_client),
    ) as (read_stream, write_stream, _):

        # Create an MCP session for making tool calls
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the session before making requests
            await session.initialize()

            # Create the tool call request with warehouse_id in _meta
            request = CallToolRequest(
                method="tools/call",
                params={
                    # Tool name for executing SQL queries
                    &quot;name&quot;: &quot;execute_sql&quot;,

                    # Dynamic arguments - typically provided by your AI agent
                    &quot;arguments&quot;: {
                        &quot;query&quot;: &quot;SELECT * FROM my_catalog.my_schema.my_table LIMIT 10&quot;
                    },

                    # Meta parameters - specify which warehouse to use
                    &quot;_meta&quot;: {
                        &quot;warehouse_id&quot;: &quot;a1b2c3d4e5f67890&quot;  # Your SQL warehouse ID
                    }
                }
            )

            # Send the request and get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_dbsql_tool_call_with_meta())

Parâmetros do servidor MCP de Pesquisa de AI _meta​

Pesquisa de AI é compatível com os seguintes parâmetros _meta:

Nome do parâmetro

Tipo

Descrição

columns

str

Lista de nomes de colunas, separados por vírgula, a serem retornados nos resultados da pesquisa.

Exemplo: "id,text,metadata"

Caso não seja especificado, todas as colunas (exceto as colunas internas que começam com "__") serão retornadas.

columns_to_rerank

str

Lista de nomes de colunas, separados por vírgulas, cujo conteúdo o modelo de reclassificação utiliza para reavaliar a pontuação. O mecanismo de reclassificação usa esse conteúdo para reavaliar todos os resultados da pesquisa, a fim de melhorar a relevância.

Exemplo: "text,title,description"

Caso não seja especificado, a reclassificação não será realizada.

filters

str

Cadeias JSON contendo filtros a serem aplicados à pesquisa. Deve ser um JSON válido.

Exemplo: '{"updated_after": "2024-01-01"}'

Caso não seja especificado, nenhum filtro será aplicado.

include_score

bool

Indica se a pontuação de similaridade deve ser incluída nos resultados retornados.

Valores suportados: "true" ou "false"

padrão: "false"

num_results

int

Número de resultados a serem retornados.

Exemplo: "5"

query_type

str

Algoritmo de busca a ser usado para recuperar resultados.

Valores suportados: "ANN" (vizinho mais próximo aproximado, default) ou "HYBRID" (combina pesquisa de vetor e palavra-chave)

padrão: "ANN"

score_threshold

float

Limite de pontuação de similaridade mínima para filtrar resultados. Resultados com pontuações abaixo deste limite são excluídos.

Exemplo: "0.7"

Caso não seja especificado, nenhum filtro de pontuação será aplicado.

Para obter informações detalhadas sobre esses parâmetros, consulte a documentação do AI Search Python SDK.

Exemplo: configure os resultados máximos e os filtros para recuperação de Pesquisa de AI​

Este exemplo mostra como usar parâmetros _meta para configurar o comportamento da Pesquisa de AI, enquanto permite consultas dinâmicas do seu agente de AI usando o SDK Python MCP oficial.

Neste cenário, você quer:

  • Limite sempre os resultados da pesquisa a exatamente 3 itens para tempos de resposta consistentes
  • Pesquise apenas a documentação recente (atualizada após 01-01-2024) para verificar a relevância.
  • Use a pesquisa híbrida para maior precisão do que a pesquisa vetorial pura
  • Retornar apenas colunas específicas (id, texto e metadados)
  • Inclua as pontuações de similaridade nos resultados.
  • Excluir resultados com índices de similaridade inferiores a 0,5.
  • Use o reordenamento nas colunas de texto e título para melhorar a relevância.

Para executar este exemplo, configure seu ambiente Python para gerenciar o desenvolvimento do MCP:

Expanda para ver o exemplo de código.

Python
# Import required libraries for MCP client and Databricks authentication
import asyncio
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult

async def run_vector_search_tool_call_with_meta():
    # Initialize Databricks workspace client for authentication
    workspace_client = WorkspaceClient()

    # Construct the MCP server URL for your specific catalog and schema
    # Replace <workspace-hostname>, YOUR_CATALOG, and YOUR_SCHEMA with your values
    mcp_server_url = "https://<workspace-hostname>/api/2.0/mcp/ai-search/YOUR_CATALOG/YOUR_SCHEMA"

    # Establish connection to the MCP server with OAuth authentication
    async with streamablehttp_client(
        url=mcp_server_url,
        auth=DatabricksOAuthClientProvider(workspace_client),
    ) as (read_stream, write_stream, _):

        # Create an MCP session for making tool calls
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the session before making requests
            await session.initialize()

            # Create the tool call request with both dynamic and preset parameters
            request = CallToolRequest(
                method="tools/call",
                params={
                    # Tool name follows the pattern: CATALOG__SCHEMA__INDEX_NAME
                    &quot;name&quot;: &quot;YOUR_CATALOG__YOUR_SCHEMA__YOUR_INDEX_NAME&quot;,

                    # Dynamic arguments - typically provided by your AI agent or user input
                    &quot;arguments&quot;: {
                        &quot;query&quot;: &quot;How do I reset my password?&quot;  # This comes from your agent
                    },

                    # Meta parameters - preset configuration to control search behavior
                    &quot;_meta&quot;: {
                        &quot;num_results&quot;: &quot;3&quot;,  # Limit to 3 results for consistent performance
                        &quot;filters&quot;: '{&quot;updated_after&quot;: &quot;2024-01-01&quot;}',  # JSON string for date filtering
                        &quot;query_type&quot;: &quot;HYBRID&quot;,  # Use hybrid search for better relevance
                        &quot;columns&quot;: &quot;id,text,metadata&quot;,  # Return only specific columns
                        &quot;score_threshold&quot;: &quot;0.5&quot;,  # Filter out results with similarity score &lt; 0.5
                        &quot;include_score&quot;: &quot;true&quot;,  # Include similarity scores in results
                        &quot;columns_to_rerank&quot;: &quot;text,title&quot;  # Use reranker on these columns for better quality
                    }
                }
            )

            # Send the request and get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_vector_search_tool_call_with_meta())

Próximos passos​

Nesta página