Aterramento com a Pesquisa do Bing

O aterramento com a Pesquisa do Bing permite que seus Agentes de IA do Azure incorporem dados da Web públicos em tempo real ao gerar respostas. Você precisa criar um recurso de Aterramento com Pesquisa do Bing e, em seguida, conectar esse recurso aos seus Agentes de IA do Azure. Quando um usuário envia uma consulta, os Agentes de IA do Azure decidem se o Aterramento com a Pesquisa do Bing deve ser aproveitado ou não. Em caso afirmativo, ele aproveitará o Bing para pesquisar dados públicos da Web e retornar partes relevantes. Por fim, os Agentes de IA do Azure usarão partes retornadas para gerar uma resposta.

Você pode fazer perguntas como "qual é a principal notícia hoje" ou "qual é a atualização recente no setor de varejo nos EUA?", que exigem dados públicos em tempo real.

Os desenvolvedores e usuários finais não têm acesso ao conteúdo bruto retornado do Aterramento com a Pesquisa do Bing. A resposta, no entanto, inclui citações com links para os sites usados para gerar a resposta e um link para a consulta do Bing usada para a pesquisa. Essas duas Referências devem ser mantidas e exibidas na forma exata fornecida pela Microsoft, de acordo com os Requisitos de Uso e Exibição da Pesquisa do Bing. Consulte a seção Como exibir o Aterramento com os resultados da Pesquisa do Bing para obter detalhes.

Importante

1. O uso do Grounding com a Pesquisa do Bing pode incorrer em custos. Consulte a página de preços para obter detalhes.
2. Ao criar e usar um recurso de Aterramento com Pesquisa do Bing por meio da experiência code-first, como a CLI do Azure, ou implantar por meio do modelo de implantação, você concorda em estar vinculado e cumprir os termos disponíveis no https://www.microsoft.com/en-us/bing/apis/grounding-legal, que podem ser atualizados periodicamente.
3. Quando você usa o Aterramento com a Pesquisa do Bing, os dados do cliente são transferidos fora do limite de conformidade do Azure para o serviço Aterramento com Pesquisa do Bing. A ligação à base com a Pesquisa do Bing não está sujeita aos mesmos termos de processamento de dados (incluindo a localização do processamento) e não tem os mesmos padrões e certificações de conformidade que o Serviço do Agente de IA do Azure, conforme descrito nos Termos de Utilização da Pesquisa de Ligação à Terra com o Bing. É sua responsabilidade avaliar se o uso do Grounding com a Pesquisa do Bing em seu agente atende às suas necessidades e requisitos.

Como funciona o Grounding com a Pesquisa do Bing

A consulta do usuário é a mensagem que um usuário final envia a um agente, como "devo levar um guarda-chuva comigo hoje? Estou em Seattle." Instruções são a mensagem do sistema que um desenvolvedor pode fornecer para compartilhar contexto e fornecer instruções para o modelo de IA sobre como usar várias ferramentas ou se comportar.

Quando um usuário envia uma consulta, a implantação do modelo de IA do cliente primeiro a processa (usando as instruções fornecidas) para depois executar uma consulta de pesquisa do Bing (que é visível para os desenvolvedores). O aterramento com o Bing retorna resultados de pesquisa relevantes para a implantação do modelo do cliente, que gera a saída final. Ao usar o Aterramento com a Pesquisa do Bing, somente a consulta de pesquisa do Bing e sua chave de recurso são enviadas para o Bing, e nenhuma informação específica do usuário final é incluída. A sua chave de recurso é enviada para o Bing apenas para efeitos de faturação e limitação de taxa. Qualquer consulta de pesquisa do Bing gerada e enviada ao Bing para fins de aterramento é transferida, juntamente com a chave de recurso, fora do limite de conformidade do Azure para o serviço Aterramento com Pesquisa do Bing. A ligação à base com a Pesquisa do Bing está sujeita aos termos do Bing e não tem os mesmos padrões de conformidade e certificações que o Serviço de Agente de IA do Azure, conforme descrito nos Termos de Utilização da Ligação à Terra com a Pesquisa do Bing. É sua responsabilidade avaliar se o uso do Grounding com a Pesquisa do Bing em seu agente atende às suas necessidades e requisitos.

Suporte de uso

Suporte de fundição de IA do Azure	Python SDK	SDK C#	SDK JavaScript	API REST	Configuração básica do agente	Configuração padrão do agente
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Configurar

Nota

1. A ligação à terra com a Pesquisa do Bing só funciona com os seguintes modelos do Azure OpenAI: gpt-3.5-turbo-0125, gpt-4-0125-preview, gpt-4-turbo-2024-04-09, gpt-4o-0513

1. Crie um Agente de IA do Azure seguindo as etapas no início rápido.

2. Crie um recurso de Aterramento com a Pesquisa do Bing. Você precisa ter owner ou contributor função em sua assinatura ou grupo de recursos para criá-lo.

   1. Você pode criar um no portal do Azure e selecionar os diferentes campos no formulário de criação. Certifique-se de criar este recurso de Aterramento com Pesquisa do Bing no mesmo grupo de recursos que seu Agente de IA do Azure, Projeto de IA e outros recursos.

   

   1. Você também pode criar uma através da experiência code-first. Em caso afirmativo, você precisará registrar manualmente a Pesquisa do Bing como um provedor de recursos do Azure. Tem de ter permissão para efetuar a operação /register/action para o fornecedor de recursos. A permissão está incluída nas funções de Colaborador e Proprietário .

       az provider register --namespace 'Microsoft.Bing'
   

3. Depois de criar um recurso de Aterramento com Pesquisa do Bing, você pode encontrá-lo no portal do Azure. Navegue até o grupo de recursos no qual você criou o recurso, procure o recurso Aterramento com Pesquisa do Bing que você criou.

   

4. Você pode adicionar a ferramenta Aterramento com Pesquisa do Bing a um agente programaticamente usando os exemplos de código listados na parte superior deste artigo ou o portal do Azure AI Foundry. Se você quiser usar o portal, na tela Criar e depurar para seu agente, role para baixo no painel Configuração à direita para conhecimento. Em seguida, selecione Adicionar.

   

5. Selecione Aterramento com a Pesquisa do Bing e siga as instruções para adicionar a ferramenta. Observe que você pode adicionar apenas um por agente.

   

6. Clique para adicionar novas conexões. Depois de adicionar uma conexão, você pode selecionar diretamente da lista existente.

   

7. Selecione o recurso Aterramento com Pesquisa do Bing que você deseja usar e clique para adicionar conexão.

   

Como exibir o Aterramento com os resultados da Pesquisa do Bing

De acordo com os termos de uso e uso e requisitos de exibição do Grounding with Bing, você precisa exibir URLs de sites e URLs de consulta de pesquisa do Bing em sua interface personalizada. Você pode encontrar URLs de sites por meio de annotations parâmetros na resposta da API e URLs de consulta de pesquisa do Bing por meio de runstep detalhes. Para renderizar a página da Web, recomendamos que você substitua o ponto de extremidade das URLs de consulta de pesquisa do Bing por www.bing.com e sua URL de consulta de pesquisa do Bing ficaria parecida com "https://www.bing.com/search?q={search consulta}"

run_steps = project_client.agents.list_run_steps(run_id=run.id, thread_id=thread.id)
run_steps_data = run_steps['data']
print(f"Last run step detail: {run_steps_data}")

Outras considerações jurídicas

A Microsoft utilizará os dados que enviar para o Grounding with Bing para melhorar os produtos e serviços Microsoft. Quando envia dados pessoais para este serviço, é responsável por obter consentimento suficiente dos titulares dos dados. Os Termos de Proteção de Dados nos Termos dos Serviços Online não se aplicam ao Grounding with Bing.

A sua utilização do Grounding com a Pesquisa do Bing será regida pelos Termos de Utilização. Ao usar o Grounding com a Pesquisa do Bing, você concorda em ficar vinculado e cumprir estes Termos de Uso.

Etapa 1: Criar um cliente de projeto

Crie um objeto cliente, que conterá a cadeia de conexão para se conectar ao seu projeto de IA e outros recursos.

Python

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import BingGroundingTool


# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

C#

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Core.TestFramework;
using NUnit.Framework;

var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;

var clientOptions = new AIProjectClientOptions();

// Adding the custom headers policy
clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);

JavaScript

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set.");
}
const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
);

API REST

Siga o Guia de início rápido da API REST para definir os valores corretos para as variáveis AZURE_AI_AGENTS_TOKEN de ambiente e AZURE_AI_AGENTS_ENDPOINT.

Etapa 2: Criar um agente com a ferramenta de pesquisa Aterramento com o Bing habilitada

Para disponibilizar a ferramenta de pesquisa Aterramento com Bing para seu agente, use uma conexão para inicializar a ferramenta e anexá-la ao agente. Você pode encontrar sua conexão na seção de recursos conectados do seu projeto no portal do Azure AI Foundry.

Python

bing_connection = project_client.connections.get(
    connection_name=os.environ["BING_CONNECTION_NAME"]
)
conn_id = bing_connection.id

print(conn_id)

# Initialize agent bing tool and add the connection id
bing = BingGroundingTool(connection_id=conn_id)

# Create agent with the bing tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o",
        name="my-assistant",
        instructions="You are a helpful assistant",
        tools=bing.definitions,
        headers={"x-ms-enable-preview": "true"}
    )
    print(f"Created agent, ID: {agent.id}")

C#

GetConnectionResponse bingConnection = await projectClient.GetConnectionsClient().GetConnectionAsync(TestEnvironment.BINGCONNECTIONNAME);
var connectionId = bingConnection.Id;

AgentsClient agentClient = projectClient.GetAgentsClient();

ToolConnectionList connectionList = new ToolConnectionList
{
    ConnectionList = { new ToolConnection(connectionId) }
};
BingGroundingToolDefinition bingGroundingTool = new BingGroundingToolDefinition(connectionList);

Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
    model: "gpt-4o",
    name: "my-assistant",
    instructions: "You are a helpful assistant.",
    tools: new List<ToolDefinition> { bingGroundingTool });
Agent agent = agentResponse.Value;

JavaScript

const bingGroundingConnectionId = "<bingGroundingConnectionId>";
const bingTool = ToolUtility.createConnectionTool(connectionToolType.BingGrounding, [
  bingGroundingConnectionId,
]);

const agent = await client.agents.createAgent("gpt-4o", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [bingTool.definition],
});
console.log(`Created agent, agent ID : ${agent.id}`);

API REST

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "instructions": "You are a helpful agent.",
        "name": "my-agent",
        "model": "gpt-4o",
        "tools": [
          {
            "type": "bing_grounding",
            "bing_grounding": {
                "connections": [
                    {
                        "connection_id": "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-bing-connection-name>"
                    }
                ]
            }
          }
        ]
      }'

Etapa 3: Criar um thread

Python

# Create thread for communication
thread = project_client.agents.create_thread()
print(f"Created thread, ID: {thread.id}")

# Create message to thread
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="What is the top news today",
)
print(f"Created message, ID: {message.id}")

C#

// Create thread for communication
Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

// Create message to thread
Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "How does wikipedia explain Euler's Identity?");
ThreadMessage message = messageResponse.Value;

JavaScript

// create a thread
const thread = await client.agents.createThread();

// add a message to thread
await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "What is the weather in Seattle?",
});

API REST

Criar um thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Adicionar uma pergunta de usuário ao thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "What is the weather in Seattle?"
    }'

Etapa 4: Criar uma execução e verificar a saída

Crie uma execução e observe que o modelo usa a ferramenta Aterramento com Pesquisa do Bing para fornecer uma resposta à pergunta do usuário.

Python

# Create and process agent run in thread with tools
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")

# Retrieve run step details to get Bing Search query link
# To render the webpage, we recommend you replace the endpoint of Bing search query URLs with `www.bing.com` and your Bing search query URL would look like "https://www.bing.com/search?q={search query}"
run_steps = project_client.agents.list_run_steps(run_id=run.id, thread_id=thread.id)
run_steps_data = run_steps['data']
print(f"Last run step detail: {run_steps_data}")

if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Delete the assistant when done
project_client.agents.delete_agent(agent.id)
print("Deleted agent")

# Fetch and log all messages
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

C#

// Run the agent
Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);

do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
}
while (runResponse.Value.Status == RunStatus.Queued
    || runResponse.Value.Status == RunStatus.InProgress);

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await agentClient.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages)
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        else if (contentItem is MessageImageFileContent imageFileItem)
        {
            Console.Write($"<image from ID: {imageFileItem.FileId}");
        }
        Console.WriteLine();
    }
}

JavaScript

  // create a run
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

API REST

Executar o thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Recuperar o status da execução

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Recuperar a resposta do agente

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Próximos passos

Veja o exemplo completo de Aterramento com a Pesquisa do Bing.