Filsökningsverktyg för Azure AI Agent Service
Filsökning utökar agenter med kunskap utanför modellen, till exempel produktinformation eller dokument som tillhandahålls av dina användare.
Kommentar
Med standardagentkonfigurationen ser det förbättrade filsökningsverktyget till att dina filer finns kvar i din egen lagring och att azure AI Search-resursen används för att mata in dem, vilket säkerställer att du har fullständig kontroll över dina data.
Filkällor
- Ladda upp lokala filer
- Azure Blob Storage
Användningsstöd
Stöd för Azure AI Foundry | Python SDK | C#-SDK | JavaScript SDK | REST-API | Grundläggande agentkonfiguration | Standardagentkonfiguration |
---|---|---|---|---|---|---|
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | Endast filuppladdning | Filuppladdning och användning av BYO-bloblagring |
Beroende av agentkonfiguration
Grundläggande agentkonfiguration
Filsökningsverktyget har samma funktioner som Azure OpenAI-assistenter. Microsofts hanterade sök- och lagringsresurser används.
- Uppladdade filer lagras i Microsofts hanterade lagring
- Ett vektorlager skapas med hjälp av en Microsoft-hanterad sökresurs
Standardagentkonfiguration
Filsökningsverktyget använder de Azure AI Search- och Azure Blob Storage-resurser som du anslöt under agentkonfigurationen.
- Uppladdade filer lagras i ditt anslutna Azure Blob Storage-konto
- Vektorlager skapas med hjälp av din anslutna Azure AI Search-resurs
För båda agentkonfigurationerna hanterar Azure OpenAI hela inmatningsprocessen, vilket omfattar:
- Parsa och segmentera dokument automatiskt
- Generera och lagra inbäddningar
- Använda både vektor- och nyckelordssökningar för att hämta relevant innehåll för användarfrågor.
Det finns ingen skillnad i koden mellan de två installationerna. den enda varianten är i var dina filer och skapade vektorlager lagras.
Hur det fungerar
Filsökningsverktyget implementerar flera metodtips för hämtning direkt för att hjälpa dig att extrahera rätt data från dina filer och utöka modellens svar. Filsökningsverktyget:
- Skriver om användarfrågor för att optimera dem för sökning.
- Delar upp komplexa användarfrågor i flera sökningar som kan köras parallellt.
- Kör både nyckelords- och semantiska sökningar i både agent- och trådvektorlager.
- Reranks sökresultat för att välja de mest relevanta innan du genererar det slutliga svaret.
- Som standard använder filsökningsverktyget följande inställningar:
- Segmentstorlek: 800 token
- Segment överlappning: 400 token
- Inbäddningsmodell: textinbäddning-3-stor vid 256 dimensioner
- Maximalt antal segment som lagts till i kontexten: 20
Vektorlager
Vektorlagringsobjekt ger filsökningsverktyget möjlighet att söka i dina filer. Genom att lägga till en fil i ett vektorlager parsas, segment, bäddas in och lagras filen i en vektordatabas som kan både nyckelords- och semantisk sökning. Varje vektorlager kan innehålla upp till 10 000 filer. Vektorlager kan kopplas till både agenter och trådar. För närvarande kan du ansluta högst ett vektorlager till en agent och högst ett vektorlager till en tråd.
På samma sätt kan dessa filer tas bort från ett vektorlager genom att antingen:
- Ta bort vektorlagringsfilobjektet eller,
- Genom att ta bort det underliggande filobjektet, som tar bort filen från alla vector_store och code_interpreter konfigurationer i alla agenter och trådar i organisationen
Den maximala filstorleken är 512 MB. Varje fil får inte innehålla fler än 5 000 000 token per fil (beräknas automatiskt när du bifogar en fil).
Säkerställa beredskap för vektorlager innan du skapar körningar
Vi rekommenderar starkt att du ser till att alla filer i en vector_store bearbetas fullständigt innan du skapar en körning. Detta säkerställer att alla data i vektorlagret är sökbara. Du kan söka efter beredskap för vektorlager med hjälp av avsökningshjälparna i SDK:erna eller genom att manuellt avsöka vektorarkivobjektet för att säkerställa att statusen har slutförts.
Som reserv finns det en maximal väntetid på 60 sekunder i körningsobjektet när trådens vektorarkiv innehåller filer som fortfarande bearbetas. Detta är för att säkerställa att alla filer som användarna laddar upp i en tråd är helt sökbara innan körningen fortsätter. Den här reservväntningen gäller inte för agentens vektorarkiv.
Lägga till filsökning till en agent med hjälp av Azure AI Foundry-portalen
Du kan lägga till Bing Search-verktyget i en agent programatiskt med hjälp av kodexemplen som visas överst i den här artikeln eller Azure AI Foundry-portalen. Om du vill använda portalen:
Snabbstart – Ladda upp lokala filer med filsökning
I det här exemplet använder vi Azure AI Agent Service för att skapa en agent som kan hjälpa dig att besvara frågor om information som du laddar upp från lokala filer.
Förutsättningar
Se till att du har rollen Storage Blob Data Contributor på projektets lagringskonto.
Se till att du har rollen Som Azure AI Developer i projektet.
Steg 1: Skapa en projektklient
Skapa ett klientobjekt som innehåller anslutningssträng för att ansluta till ditt AI-projekt och andra resurser.
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"]
)
Steg 2: Ladda upp filer och lägg till dem i ett vektorarkiv
För att komma åt dina filer använder filsökningsverktyget vektorlagringsobjektet. Ladda upp dina filer och skapa ett vektorarkiv. När du har skapat vektorarkivet avsöker du dess status tills alla filer inte är in_progress
i tillstånd för att säkerställa att allt innehåll bearbetas fullständigt. SDK:t tillhandahåller hjälp för uppladdning och avsökning.
# 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}")
Steg 3: Skapa en agent och aktivera filsökning
Om du vill göra filerna tillgängliga för din agent skapar du ett FileSearchTool
objekt med vector_store
ID:t och bifogar tools
och tool_resources
till agenten.
# 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}")
Steg 4: Skapa en tråd
Du kan också bifoga filer som bifogade filer i tråden. Om du gör det skapas en annan vector_store
som är associerad med tråden, eller om det redan finns ett vektorlager kopplat till den här tråden, bifogar de nya filerna till det befintliga trådvektorarkivet. När du skapar en Kör på den här tråden frågar filsökningsverktyget både vector_store
från din agent och vector_store
i tråden.
# 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}")
Steg 5: Skapa en körning och kontrollera utdata
Skapa en körning och observera att modellen använder filsökningsverktyget för att ge ett svar på användarens fråga.
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}")
Snabbstart – Använda befintliga filer i Azure Blob Storage med filsökning
I det här exemplet använder vi Azure AI Agent Service för att skapa en agent som kan hjälpa dig att besvara frågor om information från filer i Azure Blob Storage.
Förutsättningar
Se till att du har rollen Storage Blob Data Contributor på projektets lagringskonto.
Se till att du har rollen Som Azure AI Developer i projektet.
Viktigt!
Filsökning med bloblagring stöds endast av standardagentkonfigurationen.
Steg 1: Skapa en projektklient
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"]
)
Steg 2: Ladda upp lokala filer till projektets Azure Blob Storage-container
Ladda upp din lokala fil till projektets Azure Blob Storage-container. Det här är samma lagringskonto som du anslöt till din agent under installationen. När du skapar ytterligare agenter i samma projekt kan du återanvända tillgångs-URI:er för tidigare uppladdade filer som dessa agenter behöver. Det innebär att du inte behöver ladda upp samma fil upprepade gånger, eftersom tillgångs-URI:erna gör att du kan referera till filerna direkt.
Skapa sedan ett vektorlager med hjälp asset_uri
av , som är platsen för filen i projektets datalager.
# 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}")
Steg 3: Skapa en agent med åtkomst till filsökningsverktyget
# 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}")
Steg 4: Skapa det andra vektorarkivet med den tidigare uppladdade filen
Skapa nu ett andra vektorarkiv med hjälp av den tidigare uppladdade filen.
asset_uri
Att använda en fil som redan finns i Azure Blob Storage är användbart om du har flera agenter som behöver åtkomst till samma filer, eftersom det eliminerar behovet av att ladda upp samma fil flera gånger.
# 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}")
Steg 5: Skapa en andra agent med åtkomst till filsökningsverktyget
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}")
Filtyper som stöds
Kommentar
För text-/MIME-typer måste kodningen vara antingen utf-8, utf-16 eller ASCII.
File format | MIME-typ |
---|---|
.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 |
Skapa vektorlager och lägga till filer
Att lägga till filer i vektorlager är en asynkron åtgärd. För att säkerställa att åtgärden är klar rekommenderar vi att du använder hjälparna "skapa och avsöka" i våra officiella SDK:er. Om du inte använder SDK:erna kan du hämta vector_store
objektet och övervaka dess file_counts
egenskap för att se resultatet av filinmatningsåtgärden.
Filer kan också läggas till i ett vektorlager när det har skapats genom att skapa filer för vektorlagring.
# 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}")
Du kan också lägga till flera filer i ett vektorlager genom att skapa batchar med upp till 500 filer.
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]
)
Grundläggande agentkonfiguration: Ta bort filer från vektorlager
Filer kan tas bort från ett vektorarkiv genom att antingen:
- Ta bort vektorlagringsfilobjektet eller,
- Ta bort det underliggande filobjektet, vilket tar bort filen från alla vector_store och code_interpreter konfigurationer i alla agenter och trådar i organisationen
Den maximala filstorleken är 512 MB. Varje fil får inte innehålla fler än 5 000 000 token per fil (beräknas automatiskt när du bifogar en fil).
Ta bort vektorarkiv
Du kan ta bort ett vektorarkiv från filsökningsverktyget.
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}")
Ta bort vektorlager
project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")
Hantera kostnader med förfalloprinciper
För grundläggande agentkonfiguration file_search
använder vector_stores
verktyget objektet som resurs och du debiteras baserat på storleken på de vector_store objekt som skapats. Storleken på vektorlagringsobjektet är summan av alla parsade segment från dina filer och deras motsvarande inbäddningar.
För att hjälpa dig att hantera kostnaderna för dessa vector_store objekt har vi lagt till stöd för förfalloprinciper i vector_store
objektet. Du kan ange dessa principer när du skapar eller uppdaterar objektet 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
}
)
Trådvektorlager har standardprinciper för förfallodatum
Vektorlager som skapats med hjälp av trådhjälpare (till exempel tool_resources.file_search.vector_stores
i Trådar eller message.attachments
i Meddelanden) har en standardprincip för förfallotid på sju dagar efter att de senast var aktiva (definieras som den senaste gången vektorarkivet var en del av en körning).
När ett vektorlager upphör att gälla misslyckas körningen på den tråden. Du kan åtgärda problemet genom att återskapa en ny vector_store med samma filer och koppla den till tråden igen.