Aterramento com a Pesquisa do Bing

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 aterramento com o Bing Search e, em seguida, conectar esse recurso aos 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. Nesse caso, 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 "quais são as principais notícias de hoje" ou "qual é a atualização recente no setor de varejo nos EUA?", que exigem dados públicos em tempo real.

Os desenvolvedores e os usuários finais não têm acesso ao conteúdo bruto retornado do Aterramento com o Bing Search. 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 retidas e exibidas no formulário exato fornecido pela Microsoft, de acordo com o Aterramento com os Requisitos de Uso e Exibição da Pesquisa do Bing. Confira a seção como exibir o Aterramento com os resultados da Pesquisa do Bing para obter detalhes.

Importante

1. O uso do Aterramento com a Pesquisa do Bing pode incorrer em custos. Consulte a página de preço para obter detalhes.
2. Ao criar e usar um recurso do Aterramento com a Pesquisa do Bing por meio da experiência de início do código, como a CLI do Azure ou a implantação por meio do modelo de implantação, você concorda em estar associado e cumprir os termos disponíveis em https://www.microsoft.com/en-us/bing/apis/grounding-legal, que podem ser atualizados de tempos em tempos.

Instalação

Observação

1. O aterramento com o Bing Search 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. Registre o Bing Search manualmente como um provedor de recursos do Azure. Você precisa ter permissão para realizar a operação /register/action para o provedor de recursos. A permissão está incluída nas funções de Colaborador e Proprietário.

       az provider register --namespace 'Microsoft.Bing'
   

3. Os desenvolvedores podem criar uma nova Fundamentação com o recurso Bing Search. Crie um novo recurso aterramento com o Bing Search no portal do Azure e selecione os diferentes campos no formulário de criação. Crie esse recurso de aterramento com o Bing Search no mesmo grupo de recursos que o Agente de IA do Azure, o Projeto de IA e outros recursos.

4. Depois de criar um recurso aterramento com o Bing Search, você poderá encontrá-lo no portal do Azure. Navegue até o grupo de recursos no qual você criou o recurso, pesquise o recurso Aterramento com a Pesquisa do Bing que você criou.

   

5. Selecione o recurso Aterramento com a Pesquisa do Bing que você criou e copie qualquer uma das chaves de API.

   

6. Acesse o portal do Azure AI Foundry e selecione o Projeto de IA (verifique se ele está no mesmo grupo de recursos do recurso Aterramento com Pesquisa do Bing). Clique no centro de gerenciamento.

   

7. Selecione + nova conexão na página de configurações.

   Observação

   Se você gerar novamente a chave de API em uma data posterior, precisará atualizar a conexão com a nova chave.

   

8. Selecione a chave de API em outros tipos de recurso.

   

9. Insira as informações a seguir e, em seguida, crie uma nova conexão com o recurso Aterramento com a Pesquisa do Bing.

   • Ponto de extremidade: https://api.bing.microsoft.com/
   • Chave: YOUR_API_KEY
   • Nome da conexão: YOUR_CONNECTION_NAME (Você usará esse nome de conexão no código de exemplo abaixo.)
   • Acesso: você pode escolher somente este projeto ou compartilhado com todos os projetos. Apenas verifique se, no código de exemplo abaixo, o projeto para o qual você inseriu a cadeia de conexão tem acesso a essa conexão.

Como exibir o aterramento com os resultados da Pesquisa do Bing

De acordo com o Aterramento com os termos de uso e usar e exibir os requisitos do Bing, você precisa exibir URLs do site e URLs de consulta de pesquisa do Bing em sua interface personalizada. Você pode encontrar URLs do site por meio do parâmetro annotations na resposta à API e nas URLs de consulta de pesquisa do Bing por meio de detalhes runstep. 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 se pareceria 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 legais

A Microsoft usará os dados que você enviar para o Aterramento com o Bing para melhorar os produtos e serviços da Microsoft. Quando você envia dados pessoais para esse serviço, você é responsável por obter o consentimento suficiente das entidades de dados. Os Termos de Proteção de Dados nos Termos de Serviços Online não se aplicam ao aterramento com o Bing.

O uso do Aterramento com a Pesquisa do Bing será regido pelos Termos de Uso. Ao usar o Aterramento com a Pesquisa do Bing, você concorda em ser associado e estar em conformidade com esses Termos de Uso.

Etapa 1: criar um agente com o Aterramento com a Pesquisa do Bing

Crie um objeto cliente, que conterá a cadeia de conexão para se conectar ao projeto de IA e a 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);

Etapa 2: Habilitar o aterramento com a ferramenta de pesquisa do Bing

Para disponibilizar a ferramenta de pesquisa Aterramento com o Bing ao 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;

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;

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();
    }
}

Próximas etapas

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