Nástroj pro vyhledávání souborů služby agenta Azure AI

Vyhledávání souborů rozšiřuje agenty o znalosti mimo jeho model, například informace o vlastnických produktech nebo dokumenty poskytované uživateli.

Poznámka:

Vylepšený nástroj pro vyhledávání souborů pomocí standardního nastavení agenta zajistí, že vaše soubory zůstanou ve vašem vlastním úložišti a prostředek Služby Azure AI Search se použije k jejich ingestování a zajistí úplnou kontrolu nad vašimi daty.

Zdroje souborů

• Nahrání místních souborů
• Azure Blob Storage

Závislost na nastavení agenta

Základní nastavení agenta

Nástroj pro vyhledávání souborů má stejné funkce jako Asistenti Azure OpenAI. Používá se spravované vyhledávání a prostředky úložiště od Microsoftu.

• Nahrané soubory se ukládají ve spravovaném úložišti Microsoftu
• Vektorové úložiště se vytvoří pomocí prostředku spravovaného vyhledávání Microsoftu.

Nastavení standardního agenta

Nástroj pro vyhledávání souborů používá prostředky Azure AI Search a Azure Blob Storage, které jste připojili během instalace agenta.

• Nahrané soubory se ukládají do připojeného účtu služby Azure Blob Storage.
• Vektorové úložiště se vytvoří pomocí připojeného prostředku Azure AI Search.
  
  

U obou nastavení agentů zpracovává Azure OpenAI celý proces příjmu dat, který zahrnuje:

• Automatická analýza a blokování dokumentů
• Generování a ukládání vložených objektů
• Použití vektoru i hledání klíčových slov k načtení relevantního obsahu pro dotazy uživatelů.

V kódu mezi těmito dvěma nastaveními není žádný rozdíl; Jedinou variantou je uložení souborů a vytvořených vektorových úložišť.

Jak to funguje

Nástroj pro vyhledávání souborů implementuje několik osvědčených postupů načítání, které vám pomůžou extrahovat správná data ze souborů a rozšířit odpovědi modelu. Nástroj pro vyhledávání souborů:

• Přepíše dotazy uživatelů, aby je optimalizoval pro vyhledávání.
• Rozdělí složité dotazy uživatelů do několika vyhledávání, které může běžet paralelně.
• Spouští klíčová i sémantická hledání v úložištích vektorů agentů i vláken.
• Výsledky hledání se před vygenerováním konečné odpovědi znovu seřadí a vyberou ty nejrelevavantnější.
• Ve výchozím nastavení nástroj pro vyhledávání souborů používá následující nastavení:
  • Velikost bloku: 800 tokenů
  • Překrývající se blok dat: 400 tokenů
  • Model vkládání: text-embedding-3-large s 256 rozměry
  • Maximální počet bloků dat přidaných do kontextu: 20

Vektorová úložiště

Objekty vektorového úložiště poskytují nástroji pro vyhledávání souborů možnost prohledávat soubory. Přidání souboru do vektorového úložiště automaticky parsuje, bloky dat, vkládání a ukládá soubor do vektorové databáze, která dokáže klíčové slovo i sémantické vyhledávání. Každé úložiště vektorů může obsahovat až 10 000 souborů. Vektorová úložiště mohou být připojena k agentům i podprocesům. V současné době můžete k agentu připojit maximálně jedno vektorové úložiště a k vláknu maximálně jedno úložiště vektorů.

Podobně lze tyto soubory z úložiště vektorů odebrat buď:

• Odstraněním objektu souboru úložiště vektorů nebo
• Odstraněním základního objektu souboru, který odebere soubor ze všech vector_store a code_interpreter konfigurací ve všech agentech a vláknech ve vaší organizaci

Maximální velikost souboru je 512 MB. Každý soubor by měl obsahovat maximálně 5 000 000 tokenů na soubor (při připojení souboru se počítá automaticky).

Zajištění připravenosti úložiště vektorů před vytvořením spuštění

Důrazně doporučujeme, abyste před vytvořením spuštění zajistili, že všechny soubory v vector_store budou plně zpracovány. Tím zajistíte, že všechna data ve vašem vektorovém úložišti budou prohledávatelná. Připravenost úložiště vektorů můžete zkontrolovat pomocí pomocných rutin dotazování v sadách SDK nebo ručním dotazováním objektu úložiště vektorů, abyste zajistili, že je stav dokončen.

Jako záložní úložiště existuje 60sekundový maximální čekání v objektu spuštění, když úložiště vektorů vlákna obsahuje soubory, které se stále zpracovávají. To zajistí, aby všechny soubory, které uživatelé nahrají do vlákna, plně prohledávatelné před zahájením spuštění. Toto náhradní čekání se nevztahuje na úložiště vektorů agenta.

Rychlý start – Nahrání místních souborů pomocí vyhledávání souborů

V tomto příkladu používáme službu agenta Azure AI k vytvoření agenta, který může zodpovědět otázky týkající se informací, které nahrajete z místních souborů.

Požadavky

1. Dokončete instalaci agenta.

2. Ujistěte se, že máte roli Přispěvatel dat objektů blob služby Storage v účtu úložiště vašeho projektu.

3. Ujistěte se, že máte ve svém projektu roli Azure AI Developer .

Krok 1: Vytvoření klienta projektu

Vytvořte objekt klienta, který obsahuje 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.ai.projects.models import FileSearchTool, MessageAttachment, FilePurpose
from azure.identity import DefaultAzureCredential


# 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>;<ProjectName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

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

C#

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

// 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>;<ProjectName>"
// Customer needs to login to Azure subscription via Azure CLI and set the environment variables
var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

Krok 2: Nahrání souborů a jejich přidání do úložiště vektorů

Pro přístup k souborům používá nástroj pro vyhledávání souborů objekt úložiště vektorů. Nahrajte soubory a vytvořte vektorové úložiště. Po vytvoření úložiště vektorů se dotazujte na jeho stav, dokud všechny soubory nejsou ve in_progress stavu, aby se zajistilo, že veškerý obsah je plně zpracovávaný. Sada SDK poskytuje pomocné rutiny pro nahrávání a dotazování.

Python

# We will upload the local file and will use it for vector store creation.

#upload a file
file = project_client.agents.upload_file_and_poll(file_path='./data/product_catelog.md', purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {file.id}")

# create a vector store with the file you uploaded
vector_store = project_client.agents.create_vector_store_and_poll(file_ids=[file.id], name="my_vectorstore")
print(f"Created vector store, vector store ID: {vector_store.id}")

C#

// Upload a file and wait for it to be processed
File.WriteAllText(
    path: "sample_file_for_upload.txt",
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
Response<AgentFile> uploadAgentFileResponse = await client.UploadFileAsync(
    filePath: "sample_file_for_upload.txt",
    purpose: AgentFilePurpose.Agents);

AgentFile uploadedAgentFile = uploadAgentFileResponse.Value;

// Create a vector store with the file and wait for it to be processed.
// If you do not specify a vector store, create_message will create a vector store with a default expiration policy of seven days after they were last active
VectorStore vectorStore = await client.CreateVectorStoreAsync(
    fileIds:  new List<string> { uploadedAgentFile.Id },
    name: "my_vector_store");

Krok 3: Vytvoření agenta a povolení vyhledávání souborů

Pokud chcete zpřístupnit soubory vašemu agentu, vytvořte FileSearchTool objekt s vector_store ID a připojte tools ho k tool_resources agentu.

Python

# create a file search tool
file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

# notices that FileSearchTool as tool and tool_resources must be added or the agent will be unable to search the file
agent = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-agent",
    instructions="You are a helpful agent",
    tools=file_search_tool.definitions,
    tool_resources=file_search_tool.resources,
)
print(f"Created agent, agent ID: {agent.id}")

C#

FileSearchToolResource fileSearchToolResource = new FileSearchToolResource();
fileSearchToolResource.VectorStoreIds.Add(vectorStore.Id);

// Create an agent with toolResources and process assistant run
Response<Agent> agentResponse = await client.CreateAgentAsync(
        model: "gpt-4o-mini",
        name: "SDK Test Agent - Retrieval",
        instructions: "You are a helpful agent that can help fetch data from files you know about.",
        tools: new List<ToolDefinition> { new FileSearchToolDefinition() },
        toolResources: new ToolResources() { FileSearch = fileSearchToolResource });
Agent agent = agentResponse.Value;

Krok 4: Vytvoření vlákna

Soubory můžete také připojit jako přílohy zprávy ve vlákně. Tím se vytvoří další vector_store přidružené vlákno, nebo pokud už je k tomuto vláknu připojeno vektorové úložiště, připojí nové soubory k existujícímu úložišti vektorů vláken. Když vytvoříte spustit v tomto vlákně, nástroj pro vyhledávání souborů se dotazuje jak vector_store z vašeho agenta, tak z vector_store vlákna.

Python

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

# Upload the user provided file as a messsage attachment
message_file = project_client.agents.upload_file_and_poll(file_path='product_info_1.md', purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {message_file.id}")

# Create a message with the file search attachment
# Notice that vector store is created temporarily when using attachments with a default expiration policy of seven days.
attachment = MessageAttachment(file_id=message_file.id, tools=FileSearchTool().definitions)
message = project_client.agents.create_message(
    thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?", attachments=[attachment]
)
print(f"Created message, message ID: {message.id}")

C#

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

// Create message to thread
Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "Can you give me the documented codes for 'banana' and 'orange'?");
ThreadMessage message = messageResponse.Value;

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

Vytvořte spuštění a všimněte si, že model používá nástroj pro vyhledávání souborů k poskytnutí odpovědi na otázku uživatele.

Python

run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Created run, run ID: {run.id}")

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

project_client.agents.delete_agent(agent.id)
print("Deleted agent")

messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

C#

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

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

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await client.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();
    }
}

Rychlý start – Použití existujících souborů ve službě Azure Blob Storage s vyhledáváním souborů

V tomto příkladu používáme službu agenta Azure AI k vytvoření agenta, který může zodpovědět otázky k informacím ze souborů ve službě Azure Blob Storage.

Požadavky

1. Dokončete standardní instalaci agenta.

2. Ujistěte se, že máte roli Přispěvatel dat objektů blob služby Storage v účtu úložiště vašeho projektu.

3. Ujistěte se, že máte ve svém projektu roli Azure AI Developer .

Důležité

Vyhledávání souborů pomocí úložiště objektů blob je podporováno pouze standardním nastavením agenta.

Krok 1: Vytvoření klienta projektu

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchTool, VectorStoreDataSource, VectorStoreDataSourceAssetType
from azure.identity import DefaultAzureCredential


# 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>;<ProjectName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

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

Krok 2: Nahrání místních souborů do kontejneru Azure Blob Storage projektu

Nahrajte místní soubor do kontejneru Azure Blob Storage projektu. Jedná se o stejný účet úložiště, který jste během instalace připojili ke svému agentu. Při vytváření dalších agentů ve stejném projektu můžete znovu použít identifikátory URI prostředků všech dříve nahraných souborů, které tito agenti potřebují. To znamená, že nemusíte opakovaně nahrávat stejný soubor, protože identifikátory URI prostředků umožňují přímo odkazovat na soubory.

Pak pomocí úložiště dat projektu vytvořte vektorové úložiště asset_uri, což je umístění souboru v úložišti dat projektu.

# We'll upload the local file to your project Azure Blob Storage container and will use it for vector store creation.
_, asset_uri = project_client.upload_file("sample_file_for_upload.md")
print(f"Uploaded file, asset URI: {asset_uri}")

# create a vector store with a file in blob storage and wait for it to be processed
ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[ds], name="sample_vector_store")
print(f"Created vector store, vector store ID: {vector_store.id}")

Krok 3: Vytvoření agenta s přístupem k nástroji pro vyhledávání souborů

# create a file search tool
file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
agent_1 = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant",
    instructions="You are helpful assistant",
    tools=file_search_tool.definitions,
    tool_resources=file_search_tool.resources,
)
# [END upload_file_and_create_agent_with_file_search]
print(f"Created agent_1, agent_1 ID: {agent_1.id}")

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

message = project_client.agents.create_message(
    thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?"
)
print(f"Created message, message ID: {message.id}")

run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent_1.id)

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

project_client.agents.delete_agent(agent.id)
print("Deleted agent")

messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

Krok 4: Vytvoření druhého úložiště vektorů pomocí dříve nahraného souboru

Teď vytvořte druhé úložiště vektorů pomocí dříve nahraného souboru. asset_uri Použití souboru, který už je ve službě Azure Blob Storage, je užitečné, pokud máte více agentů, kteří potřebují přístup ke stejným souborům, protože eliminuje nutnost nahrávat stejný soubor několikrát.

# create a vector store with a previously uploaded file and wait for it to be processed
ds_2 = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
vector_store_2 = project_client.agents.create_vector_store_and_poll(data_sources=[ds_2], name="sample_vector_store_2")
print(f"Created vector store, vector store ID: {vector_store.id}")

Krok 5: Vytvoření druhého agenta s přístupem k nástroji pro vyhledávání souborů

file_search_tool_2 = FileSearchTool(vector_store_ids=[vector_store_2.id])
# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
agent_2 = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant-2",
    instructions="You are helpful assistant",
    tools=file_search_tool_2.definitions,
    tool_resources=file_search_tool_2.resources,
)
# [END upload_file_and_create_agent_with_file_search]
print(f"Created agent, agent ID: {agent_2.id}")

Podporované typy souborů

Poznámka:

U typů text/MIME musí být kódování buď utf-8, utf-16 nebo ASCII.

File format	Typ MIME
.c	text/x-c
.cs	text/x-csharp
.cpp	text/x-c++
.doc	application/msword
.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html	text/html
.java	text/x-java
.json	application/json
.md	text/markdown
.pdf	application/pdf
.php	text/x-php
.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
.py	text/x-python
.py	text/x-script.python
.rb	text/x-ruby
.tex	text/x-tex
.txt	text/plain
.css	text/css
.js	text/javascript
.sh	application/x-sh
.ts	application/typescript

Vytváření vektorových úložišť a přidávání souborů

Přidání souborů do vektorových úložišť je asynchronní operace. Abyste měli jistotu, že je operace dokončená, doporučujeme použít pomocné rutiny pro vytváření a hlasování v našich oficiálních sadách SDK. Pokud sady SDK nepoužíváte, můžete načíst vector_store objekt a monitorovat jeho file_counts vlastnost, abyste viděli výsledek operace příjmu souborů.

Soubory lze také přidat do vektorového úložiště po vytvoření vytvořením souborů vektorového úložiště.

# create a vector store with no file and wait for it to be processed
vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[], name="sample_vector_store")
print(f"Created vector store, vector store ID: {vector_store.id}")

# add the file to the vector store or you can supply file ids in the vector store creation
vector_store_file_batch = project_client.agents.create_vector_store_file_batch_and_poll(
    vector_store_id=vector_store.id, file_ids=[file.id]
)
print(f"Created vector store file batch, vector store file batch ID: {vector_store_file_batch.id}")

Alternativně můžete do úložiště vektorů přidat několik souborů vytvořením dávek až 500 souborů.

batch = project_client.agents.create_vector_store_file_batch_and_poll(
  vector_store_id=vector_store.id,
  file_ids=[file_1.id, file_2.id, file_3.id, file_4.id, file_5.id]
)

Základní nastavení agenta: Odstraňování souborů z vektorových úložišť

Soubory lze z vektorového úložiště odebrat:

• Odstraněním objektu souboru úložiště vektorů nebo
• Odstranění základního objektu souboru, který odebere soubor ze všech konfigurací vector_store a code_interpreter napříč všemi agenty a vlákny ve vaší organizaci

Maximální velikost souboru je 512 MB. Každý soubor by měl obsahovat maximálně 5 000 000 tokenů na soubor (při připojení souboru se počítá automaticky).

Odebrání úložiště vektorů

Z nástroje pro vyhledávání souborů můžete odebrat vektorové úložiště.

file_search_tool.remove_vector_store(vector_store.id)
print(f"Removed vector store from file search, vector store ID: {vector_store.id}")

project_client.agents.update_agent(
    assistant_id=agent.id, tools=file_search_tool.definitions, tool_resources=file_search_tool.resources
)
print(f"Updated agent, agent ID: {agent.id}")

Odstranění úložišť vektorů

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

Správa nákladů pomocí zásad vypršení platnosti

Pro základní nastavení file_search agenta nástroj použije vector_stores objekt jako prostředek a účtuje se vám velikost vytvořených objektů vector_store. Velikost objektu úložiště vektorů je součet všech parsovaných bloků dat z vašich souborů a jejich odpovídajících vložených objektů.

Abychom vám pomohli se správou nákladů spojených s těmito vector_store objekty, přidali jsme do objektu vector_store podporu zásad vypršení platnosti. Tyto zásady můžete nastavit při vytváření nebo aktualizaci objektu vector_store .

vector_store = project_client.agents.create_vector_store_and_poll(
  name="Product Documentation",
  file_ids=[file_1.id],
  expires_after={
      "anchor": "last_active_at",
      "days": 7
  }
)

Úložiště vektorů vláken mají výchozí zásady vypršení platnosti.

Vektorová úložiště vytvořená pomocí pomocných rutin vláken (například tool_resources.file_search.vector_stores ve vláknech nebo message.attachments ve zprávách) mají výchozí zásadu vypršení platnosti sedm dnů po jejich poslední aktivní (definováno jako poslední, kdy bylo úložiště vektorů součástí spuštění).

Když vyprší platnost úložiště vektorů, spuštění v daném vlákně selže. Pokud chcete tento problém vyřešit, můžete znovu vytvořit nový vector_store se stejnými soubory a znovu ho připojit k vláknu.