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

Pesquisa na Web no Databricks

Esta página descreve como fundamentar respostas com informação em tempo real da Web no Databricks. Use o Model Context Protocol (MCP) serviço gerenciado e independente de modelo system.ai.web_search com clientes e agentes compatíveis com MCP. Os modelos básicos Gemini e OpenAI também fornecem pesquisa nativa na Web por meio de Foundation Model APIs.

prompt

Genie Code (modo agente) pode fazer isso por você. Experimente este prompt de exemplo:

Query the databricks-gemini-3-1-pro model using the OpenAI client with the google_search parameter enabled, ask a question about a current event, and print the response.

O que é uma pesquisa na web?​

A pesquisa na Web permite que os modelos de base recuperem informações atualizadas da internet durante a geração de respostas. Quando a pesquisa na web está ativada, o modelo pode pesquisar na web para encontrar informações relevantes e incorporá-las em sua resposta. Isso é útil para perguntas sobre eventos atuais, dados recentes ou qualquer tópico em que o conhecimento profundo do momento (tempo real informat) melhora a resposta.

Use a pesquisa na web​

Use um serviço gerenciar MCP independentemente do seu provedor de modelo ou habilite a pesquisa nativa na web por meio de uma API de modelo compatível:

  • Pesquisa na Web MCP gerenciada: Use o serviço MCP integrado de um cliente ou agente compatível com MCP. -> Let's stick closer to the original `target_text` structure while integrating the terms: Managed MCP web search -> Managed MCP web search (or "Gerenciado MCP web search"). The target text had "Managed MCP web search". "Managed" -> "gerenciado". Target text: ` Managed MCP web search: Use the built-in serviço MCP from an MCP-compatible client or agent.` Let's apply "built-in" -> "integrado" (modifying "serviço"): `Use o serviço MCP integrado`. Reintegrated text: Managed MCP web search: Use o serviço MCP integrado de um cliente ou agente compatível com MCP.system.ai.web_search O Databricks gerencia o modelo de suporte, portanto, você não escolhe um modelo para o serviço.
  • Modelos Gemini : Use o parâmetro google_search com a API Chat Completions ou a API Google Gemini.
  • Modelos OpenAI : Use a ferramenta web_search com a API OpenAI Responses.
  • Pesquisa na Web MCP de terceiros : use um servidor MCP de pesquisa na web, como You.com do Databricks Marketplace, como alternativa.
importante

A pesquisa na web nativa para modelos da OpenAI está disponível apenas por meio da API Responses. Não há suporte para isso por meio da API de Conclusão do Chat.

Pesquisa na Web nativa por meio de APIs de modelo​

The following examples enable a model provider's native web search tool in a Foundation Model API request.

Modelos Gemini com a API de Complementos de Chat​

Para habilitar a pesquisa na web para modelos Gemini usando a API Chat Completions, passe google_search como um parâmetro de nível superior no corpo da solicitação.

Python
import os
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('DATABRICKS_BASE_URL')

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=DATABRICKS_BASE_URL
)

response = client.chat.completions.create(
    model="databricks-gemini-3-1-pro",
    messages=[
        {"role": "user", "content": "What are the best Italian restaurants in San Francisco?"}
    ],
    extra_body={"google_search": {}}
)

print(response.choices[0].message.content)

Modelos Gemini com a API Gemini do Google​

Para habilitar a pesquisa na web usando a API Google Gemini, passe google_search como ferramenta.

Python
from google import genai
from google.genai import types
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = genai.Client(
    api_key="databricks",
    http_options=types.HttpOptions(
        base_url="https://example.staging.cloud.databricks.com/ai-gateway/gemini",
        headers={
            "Authorization": f"Bearer {DATABRICKS_TOKEN}",
        },
    ),
)

response = client.models.generate_content(
    model="databricks-gemini-3-1-pro",
    contents=[
        types.Content(
            role="user",
            parts=[types.Part(text="What are the best Italian restaurants in San Francisco?")],
        ),
    ],
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)

print(response.text)

Modelos OpenAI com a API de Respostas​

Para habilitar a pesquisa na web para modelos OpenAI, passe web_search como ferramenta usando a API OpenAI Responses.

Python
import os
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
DATABRICKS_BASE_URL = os.environ.get('DATABRICKS_BASE_URL')

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=DATABRICKS_BASE_URL
)

response = client.responses.create(
    model="databricks-gpt-5",
    input=[
        {"role": "user", "content": "What are the best Italian restaurants in San Francisco?"}
    ],
    tools=[{"type": "web_search"}]
)

print(response.output_text)

Pesquisa na web por meio do MCP​

Clientes e agentes compatíveis com MCP podem chamar uma ferramenta de pesquisa na web independentemente do provedor de modelos deles. Conecte seu cliente ou agente a um serviço ou servidor MCP de pesquisa na web usando o MCP.

A ferramenta de pesquisa na web nativa da Anthropic não está disponível por meio das APIs do Foundation Model do Databricks. Use o MCP para fornecer ferramentas de pesquisa na web a agentes que usam modelos da Anthropic.

info

Unity Gateway Beta

To use system.ai.dbsql, system.ai.sandbox, or system.ai.web_search, an account admin must enable the Unity Gateway beta from the account console Previews page. See Gerenciar account previews.

Use o serviço MCP de pesquisa web gerenciado​

The Databricks-provided MCP serviço system.ai.web_search searches the public web without a Marketplace installation or a third-party API key. The serviço is model agnostic and works with MCP-compatible clients and agents, regardless of their model provider.

O Databricks gerencia o modelo usado pelo serviço. Você não seleciona ou configura o modelo de suporte dele. Sua ferramenta web_search aceita apenas um query em linguagem natural e retorna uma resposta sintetizada com citações.

Requisitos​

O seu workspace deve atender aos requisitos dos serviços MCP. O chamador deve ter EXECUTE no serviço, USE CATALOG em system e USE SCHEMA em system.ai. Os usuários da account têm esses privilégios por default.

Conectar um cliente​

A URL do serviço é:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.web_search

Por exemplo, para conectar o cliente Claude Code, instale e configure a CLI do Unity Gateway, adicione o serviço e inicie o Claude Code:

Bash
ug mcp add --agents claude --names system.ai.web_search
ug claude

A CLI do Unity Gateway autentica por meio do seu login na CLI do Databricks e faz o refresh do token automaticamente. Para outros clientes, consulte Outros clientes MCP.

Para código de agente, consulte Usar ferramentas MCP em um agente Python.

Configure o servidor MCP da You.com​

O You.com é uma alternativa de terceiros para clientes e agentes compatíveis com MCP.

  1. Navegue até Marketplace > Agentes > Servidores MCP no seu workspace Databricks .
  2. Procure por You.com e clique em Instalar .
  3. Configure a conexão:
  • Nome da conexão : Insira um nome (por exemplo, youcom_web_search).
  • Tokens de portador : Insira sua key API da You.com.
  1. Clique em Instalar .
  2. Conceda privilégios de USAR CONEXÃO aos usuários ou grupos apropriados em Catálogo > Conexões > [sua conexão] > Permissões .

Após a configuração, o servidor MCP fica disponível como uma ferramenta no AI Playground, em agentes e em outros clientes compatíveis com MCP. O URL do endpoint do proxy para sua conexão é:

https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>

Usar o You.com com o Claude Code​

To use You.com with Claude Code and Databricks Foundation Model APIs, add the You.com MCP server:

Bash
claude mcp add youcom-search \
  --transport http \
  --url "https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>" \
  --header "Authorization: Bearer <your-databricks-pat>"

Verifique se o servidor foi adicionado com claude mcp list.

Alternativamente, adicione o servidor diretamente a ~/.claude.json:

JSON
{
  "mcpServers": {
    "youcom-search": {
      "type": "http",
      "url": "https://<workspace_host>.databricks.com/api/2.0/mcp/external/<connection_name>",
      "headers": {
        "Authorization": "Bearer <your-databricks-pat>"
      }
    }
  }
}

Modelos suportados​

A pesquisa na web do MCP exige um cliente ou agente que possa chamar ferramentas MCP. Não se limita a um provedor de modelo específico. Para integração de agentes, consulte Usar ferramentas MCP em um agente Python.

Os seguintes requisitos de modelo se aplicam apenas à pesquisa na web nativa por meio das APIs do Gemini e da OpenAI. A pesquisa na web nativa é compatível com todos os modelos base do Gemini e da OpenAI com pagamento por tokens. Consulte a Lista detalhada de modelos suportados pelas APIs do Foundation Model do Databricks para ver a disponibilidade regional.

Modelos Gemini​

  • databricks-gemini-3-1-pro
  • databricks-gemini-3-1-flash-lite
  • databricks-gemini-3-flash

modelos OpenAI​

  • databricks-gpt-5-5-pro
  • databricks-gpt-5-5
  • databricks-gpt-5-4
  • databricks-gpt-5-4-mini
  • databricks-gpt-5-4-nano
  • databricks-gpt-5-3-codex
  • databricks-gpt-5-2
  • databricks-gpt-5-1
  • databricks-gpt-5
  • databricks-gpt-5-mini
  • databricks-gpt-5-nano

Privacidade e retenção de dados​

Ao habilitar a pesquisa na web por meio das APIs do Foundation Model do Databricks, a pesquisa entra em execução em um Endpoint de modelo básico hospedado pelo Databricks. A query de pesquisa e os resultados são processados pelo modelo hospedado, independentemente de qual modelo seu aplicativo chame. Os mesmos termos de proteção e retenção de dados que regem o Model Serving se aplicam a estas solicitações:

  • O Databricks não usa entradas enviadas ao Model Serving, ou saídas dele, para ensinar modelos. Consulte proteção de dados do Model Serving.
  • Qualquer armazenamento temporário para detecção de abuso é mantido na mesma região que seu workspace e é limitado pelo tempo. Consulte Retenção de dados.

O modelo formula queries de pesquisa a partir do seu prompt e as envia para um provedor de pesquisa externo para recuperar resultados. Trate o conteúdo do prompt que chega à pesquisa na web como dados que saem da Databricks para o provedor de pesquisa e limite o que seu aplicativo envia de acordo.

Limitações​

  • A pesquisa na Web não está disponível para espaços de trabalho com compliance HIPAA/BAA ativada, pois as consultas de pesquisa na Web são enviadas para serviços de pesquisa externos que não estão em conformidade com HIPAA .

  • Os resultados das buscas na web dependem da capacidade do modelo de formular consultas de busca e sintetizar resultados. A qualidade da resposta pode variar.

  • A pesquisa web nativa por meio das APIs do Gemini e da OpenAI está disponível apenas em Endpoint de modelo de fundação com pagamento por token. Essa restrição não se aplica ao modelo que chama uma ferramenta de pesquisa web por meio do MCP.

  • O system.ai.web_search MCP serviço integrado está disponível em regiões dos EUA suportadas ou em workspaces que permitem o processamento cross-geo. Consulte Serviços MCP fornecidos pela Databricks para disponibilidade e limitações.

  • O serviço MCP integrado não está disponível quando os controles de rede do workspace desativam o acesso à internet.

  • Native web search for OpenAI models is only available through the Responses API. The Chat Completions API does not support native web search for OpenAI models.

  • A pesquisa na web nativa para modelos Gemini não está disponível quando o processamento entre regiões está desativado. O Gemini não oferece suporte ao processamento de pesquisa na mesma região geográfica, portanto, qualquer workspace com imposição de residência de dados é inelegível.

  • A pesquisa web nativa para modelos da OpenAI não está disponível quando o processamento entre regiões está desativado, a menos que o workspace esteja em uma região geográfica elegível (Américas ou Europa). A OpenAI oferece suporte ao processamento de pesquisa na mesma região geográfica nestas regiões.

Recursos adicionais​

Nesta página