Uzemnění pomocí vyhledávání Bingem

Uzemnění pomocí vyhledávání Bingu umožňuje agentům Azure AI začlenit veřejná webová data v reálném čase při generování odpovědí. Potřebujete vytvořit uzemnění s prostředkem Vyhledávání Bingu a pak tento prostředek připojit k agentům Azure AI. Když uživatel odešle dotaz, agenti Azure AI se rozhodnou, jestli by se mělo využít uzemnění vyhledávání Bingem nebo ne. Pokud ano, použije Bing k vyhledávání veřejných webových dat a vrácení relevantních bloků dat. Nakonec agenti Azure AI použijí vrácené bloky dat k vygenerování odpovědi.

Můžete se ptát, například "co je dnes nejlepší novinky" nebo "jaká je nedávná aktualizace v maloobchodě v USA?", která vyžadují veřejná data v reálném čase.

Vývojáři a koncoví uživatelé nemají přístup k nezpracovaného obsahu vráceného ze základního vyhledávání Bingem. Odpověď však obsahuje citace s odkazy na weby použité k vygenerování odpovědi a odkaz na dotaz Bing použitý pro vyhledávání. Tyto dva odkazy musí být zachovány a zobrazeny v přesné podobě poskytované Microsoftem v souladu s požadavky na použití a zobrazení vyhledávání Bingu. Podrobnosti najdete v části s informacemi o tom, jak zobrazit grounding s výsledky hledání Bingem.

Důležité

1. Využití uzemnění vyhledávání Bingem může mít za následek náklady. Podrobnosti naleznete na stránce s cenami.
2. Vytvořením a použitím zemnění s prostředkem Vyhledávání Bingem prostřednictvím prostředí pro první kód, jako je Azure CLI nebo nasazení prostřednictvím šablony nasazení, souhlasíte s tím, že budete vázáni a dodržovat podmínky, které jsou k dispozici https://www.microsoft.com/en-us/bing/apis/grounding-legalv čase, které se můžou čas od času aktualizovat.
3. Když používáte grounding s vyhledáváním Bingem, vaše zákaznická data se přenesou mimo hranice dodržování předpisů Azure do uzemnění se službou Bing Search. Zemnění vyhledávání Bingem podléhá stejným podmínkám zpracování dat (včetně umístění zpracování) a nemá stejné standardy dodržování předpisů a certifikace jako služba agenta Azure AI, jak je popsáno v tématu Základy používání podmínek vyhledávání Bingu. Je vaší zodpovědností posoudit, jestli použití groundingu s vyhledáváním Bingem v agentu splňuje vaše potřeby a požadavky.

Jak funguje uzemnění pomocí vyhledávání Bingu

Dotaz uživatele je zpráva, že koncový uživatel odešle agentu, například "mám si dnes vzít deštník? Jsem v Seattlu." Pokyny jsou systémová zpráva, kterou může vývojář poskytnout ke sdílení kontextu a poskytnout pokyny k modelu AI, jak používat různé nástroje nebo se chovat.

Když uživatel odešle dotaz, nasazení modelu AI zákazníka ho nejprve zpracuje (pomocí uvedených pokynů) k pozdějšímu provedení vyhledávacího dotazu Bingu (který je viditelný vývojářům). Při zemnění pomocí Bingu se vrátí relevantní výsledky hledání do nasazení modelu zákazníka, které pak vygeneruje konečný výstup. Při použití zemnění s vyhledáváním Bingem se do Bingu posílají jenom vyhledávací dotaz Bingu a váš klíč prostředku a nejsou zahrnuty žádné informace specifické pro koncové uživatele. Váš klíč prostředku se odesílá do Bingu výhradně pro účely fakturace a omezování sazby. Všechny vyhledávací dotazy Bingu, které se generují a odesílají Do Bingu pro účely uzemnění, se přenesou spolu s klíčem prostředku mimo hranice dodržování předpisů Azure do uzemnění se službou Bing Search. Základy vyhledávání Bingem podléhají podmínkám Bingu a nemají stejné standardy dodržování předpisů a certifikace jako služba agenta Azure AI, jak je popsáno v tématu Základy podmínek použití Vyhledávání Bingu. Je vaší zodpovědností posoudit, jestli použití groundingu s vyhledáváním Bingu ve vašem agentu splňuje vaše potřeby a požadavky.

Podpora využití

Podpora Azure AI Foundry	Python SDK	C# SDK	JavaScript SDK	REST API	Základní nastavení agenta	Nastavení standardního agenta
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Nastavení

Poznámka:

1. Uzemnění pomocí vyhledávání Bingu funguje pouze s následujícími modely Azure OpenAI: gpt-3.5-turbo-0125, gpt-4-0125-preview, , gpt-4-turbo-2024-04-09gpt-4o-0513

1. Podle kroků v rychlém startu vytvořte agenta Azure AI.

2. Vytvoření uzemnění s využitím prostředku Vyhledávání Bingem Abyste ho mohli vytvořit, musíte mít owner ve svém předplatném nebo skupině prostředků roli contributor .

   1. Můžete ho vytvořit na webu Azure Portal a vybrat různá pole ve formuláři pro vytvoření. Ujistěte se, že jste vytvořili toto uzemnění s prostředkem Vyhledávání Bingem ve stejné skupině prostředků jako agent Azure AI, projekt AI a další prostředky.

   

   1. Můžete ho také vytvořit prostřednictvím prostředí pro první kód. Pokud ano, musíte ručně zaregistrovat vyhledávání Bingu jako poskytovatele prostředků Azure. Pro daného poskytovatele prostředků musíte mít oprávnění k provedení operace /register/action. Oprávnění je součástí rolí Přispěvatel a Vlastník .

       az provider register --namespace 'Microsoft.Bing'
   

3. Jakmile vytvoříte uzemnění s prostředkem Vyhledávání Bingu, najdete ho na webu Azure Portal. Přejděte do skupiny prostředků, ve které jste prostředek vytvořili, vyhledejte uzemnění s prostředkem Vyhledávání Bingu, který jste vytvořili.

   

4. Pomocí příkladů kódu uvedených v horní části tohoto článku nebo portálu Azure AI Foundry můžete do agenta programově přidat nástroj Grounding with Bing Search. Pokud chcete použít portál, posuňte se na obrazovce Vytvořit a ladit pro svého agenta dolů v podokně Nastavení napravo od znalostí. Pak vyberte Přidat.

   

5. Vyberte Uzemnění pomocí vyhledávání Bingu a podle pokynů přidejte nástroj. Všimněte si, že můžete přidat pouze jeden agent.

   

6. Kliknutím přidáte nová připojení. Po přidání připojení můžete přímo vybrat z existujícího seznamu.

   

7. Vyberte uzemnění s prostředkem Vyhledávání Bingu, který chcete použít, a kliknutím přidejte připojení.

   

Jak zobrazit zemnění s výsledky hledání Bingem

Podle podmínek použití a použití Bingu a požadavků na zobrazení musíte ve vlastním rozhraní zobrazit jak adresy URL webu, tak adresy URL vyhledávacích dotazů Bingu. Adresy URL webu můžete najít prostřednictvím annotations parametru v odpovědi rozhraní API a adresách URL vyhledávacích dotazů Bingu prostřednictvím runstep podrobností. Pokud chcete webovou stránku vykreslit, doporučujeme nahradit koncový bod adres URL vyhledávacích dotazů Bingu www.bing.com a adresa URL vyhledávacího dotazu Bingu by vypadala jakohttps://www.bing.com/search?q={search dotaz}.

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

Další právní aspekty

Microsoft bude používat data, která odesíláte do groundingu s Bingem, aby se zlepšily produkty a služby Microsoftu. Pokud do této služby odesíláte osobní údaje, zodpovídáte za získání dostatečného souhlasu subjektů údajů. Podmínky ochrany dat v podmínkách online služeb se nevztahují na zemnění s Bingem.

Vaše použití zemnění s vyhledáváním Bingem se bude řídit podmínkami použití. Použitím zemnění s vyhledáváním Bingem souhlasíte s tím, že budete vázáni a dodržovat tyto podmínky použití.

Krok 1: Vytvoření klienta projektu

Vytvořte objekt klienta, který bude obsahovat připojovací řetězec pro připojení k projektu AI a dalším prostředkům.

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

REST API

Postupujte podle rychlého startu rozhraní REST API a nastavte správné hodnoty proměnných AZURE_AI_AGENTS_TOKEN prostředí a AZURE_AI_AGENTS_ENDPOINT.

Krok 2: Vytvoření agenta s povoleným vyhledávacím nástrojem Bingu

Pokud chcete, aby byl nástroj pro vyhledávání Bingu dostupný pro vašeho agenta, použijte připojení k inicializaci nástroje a jeho připojení k agentu. Připojení najdete v části připojené zdroje projektu na portálu 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}`);

REST API

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>"
                    }
                ]
            }
          }
        ]
      }'

Krok 3: Vytvoření vlákna

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

REST API

Vytvoření vlákna

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 ''

Přidání otázky uživatele do vlákna

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

Krok 4: Vytvoření spuštění a kontrola výstupu

Vytvořte spuštění a všimněte si, že model používá grounding s nástrojem Bing Search k poskytnutí odpovědi na otázku uživatele.

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

REST API

Spuštění vlákna

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",
  }'

Načtení stavu spuštění

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

Načtení odpovědi agenta

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

Další kroky

Podívejte se na úplnou ukázku groundingu pomocí vyhledávání Bingu.