Herramienta de búsqueda de archivos del servicio de agente de Azure AI
La búsqueda de archivos permite a los agentes acceder a información externa a su modelo, como datos específicos de productos o documentos que los usuarios les proporcionen.
Nota:
Con la configuración estándar del agente, la herramienta de búsqueda de archivos mejorada garantiza que los archivos permanezcan en su propio almacenamiento y que el recurso de Azure AI Search se use para ingerirlos, lo que garantiza que se mantiene un control completo sobre los datos.
Orígenes de archivo
- Carga de archivos locales
- Azure Blob Storage
Dependencia de la configuración del agente
Instalación básica del agente
La herramienta de búsqueda de archivos tiene la misma funcionalidad que los asistentes de Azure OpenAI. Se usan recursos de búsqueda y almacenamiento administrados por Microsoft.
- Los archivos cargados se almacenan en el almacenamiento administrado de Microsoft
- Se crea un almacén de vectores mediante un recurso de búsqueda administrada de Microsoft.
Configuración del agente estándar
La herramienta de búsqueda de archivos usa los recursos de Búsqueda de Azure AI y Azure Blob Storage que ha conectado durante la configuración del agente.
- Los archivos cargados se almacenan en la cuenta de Azure Blob Storage conectada
- Los almacenes de vectores se crean mediante el recurso de Búsqueda de Azure AI conectado
En ambas configuraciones del agente, Azure OpenAI controla todo el proceso de ingesta, que incluye:
- Analizar y fragmentar documentos automáticamente.
- Generar y almacenar inserciones.
- Usar búsquedas de vectores y palabras clave para recuperar contenido relevante para las consultas de usuario.
No hay ninguna diferencia en el código entre las dos configuraciones; la única variación es donde se almacenan los archivos y los almacenes de vectores creados.
Funcionamiento
La herramienta de búsqueda de archivos implementa varios procedimientos recomendados de recuperación listas para ayudarle a extraer los datos adecuados de los archivos y aumentar las respuestas del modelo. La herramienta de búsqueda de archivos:
- Vuelve a escribir consultas de usuario para optimizarlas para la búsqueda.
- Divide las consultas de usuario complejas en varias búsquedas que se pueden ejecutar en paralelo.
- Ejecuta búsquedas semánticas y por palabra clave en almacenes de vectores de subproceso y de agente.
- Vuelve a generar los resultados de búsqueda para elegir los más relevantes antes de generar la respuesta final.
- De forma predeterminada, la herramienta de búsqueda de archivos usa la siguiente configuración:
- Tamaño del fragmento: 800 tokens
- Superposición de fragmentos: 400 tokens
- Modelo de inserción: inserción de texto-3-large a 256 dimensiones
- Número máximo de fragmentos agregados al contexto: 20
Almacenes de vectores
Los objetos de almacén de vectores proporcionan a la herramienta de búsqueda de archivos la capacidad de buscar archivos. Al agregar un archivo a un almacén de vectores, se analizan, fragmentos, incrustaciones y se almacena el archivo en una base de datos vectorial capaz de buscar palabra clave y semántica. Cada almacén de vectores puede contener hasta 10 000 archivos. Los almacenes de vectores se pueden asociar tanto a agentes como a subprocesos. Actualmente, puede asociar como máximo un almacén de vectores a un asistente y, como máximo, un almacén de vectores a un subproceso.
Del mismo modo, estos archivos se pueden quitar de un almacén de vectores mediante:
- Eliminar el objeto de archivo de almacén de vectores o,
- Eliminando el objeto de archivo subyacente (que quita el archivo de todas las configuraciones de vector_store y code_interpreter de todos los agentes y subprocesos de la organización).
El tamaño máximo de archivo es de 512 MB. Cada archivo no debe contener más de 5 000 000 tokens por archivo (calculado automáticamente al adjuntar un archivo).
Garantizar la preparación del almacén de vectores antes de crear ejecuciones
Se recomienda encarecidamente asegurarse de que todos los archivos de un vector_store se procesan completamente antes de crear una ejecución. Esto garantiza que se puedan buscar todos los datos del almacén de vectores. Puede comprobar la preparación del almacén de vectores mediante los asistentes de sondeo de los SDK o sondeando manualmente el objeto de almacén de vectores para asegurarse de que el estado se ha completado.
Como reserva, hay una espera máxima de 60 segundos en el objeto de ejecución cuando el almacén de vectores del subproceso contiene archivos que todavía se están procesando. Esto es para asegurarse de que los archivos que los usuarios carguen en un subproceso sean totalmente buscables antes de continuar la ejecución. Esta espera de reserva no se aplica al almacén de vectores del agente.
Inicio rápido: Carga de archivos locales con búsqueda de archivos
En este ejemplo, usamos el servicio de agente de Azure AI para crear un agente que pueda ayudar a responder a preguntas sobre la información que cargue desde archivos locales.
Requisitos previos
Complete la configuración del agente.
Asegúrese de que tiene el rol Colaborador de datos de Storage Blob en la cuenta de almacenamiento del proyecto.
Asegúrese de que tiene el rol Desarrollador de Azure AI en el proyecto.
Paso 1: Creación de un cliente de proyecto
Cree un objeto de cliente que contenga la cadena de conexión para conectarse al proyecto de IA y a otros recursos.
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"]
)
Paso 2: Carga archivos y su incorporación a un almacén de vectores
Para acceder a los archivos, la herramienta de búsqueda de archivos usa el objeto de almacén vectorial. Cargue los archivos y cree un almacén de vectores. Después de crear el almacén de vectores, sondee su estado hasta que todos los archivos estén fuera del estado in_progress para asegurarse de que todo el contenido se está procesando completamente. El SDK proporciona asistentes para cargar y sondear.
# 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}")
Paso 3: Creación de un agente y habilitación de la búsqueda de archivos
Para que los archivos sean accesibles para el agente, cree un objeto FileSearchTool con el identificador vector_store y asocie tools y tool_resources al agente.
# 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}")
Paso 4: Creación de un subproceso
También puede adjuntar archivos como datos adjuntos de mensajes en el subproceso. Al hacerlo, se crea otro objeto vector_store asociado al subproceso o, si ya hay un almacén de vectores asociado a este subproceso, se asocian los nuevos archivos al almacén de vectores de subproceso existente. Al crear una ejecución en este subproceso, la herramienta de búsqueda de archivos consulta el objeto vector_store desde el agente y el objeto vector_store en el subproceso.
# 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}")
Paso 5: Creación de una ejecución y comprobación de la salida
Cree una ejecución y observe que el modelo usa la herramienta de búsqueda de archivos para proporcionar una respuesta a la pregunta del usuario.
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}")
Inicio rápido: Uso de archivos existentes en Azure Blob Storage con búsqueda de archivos
En este ejemplo, se usa el servicio de agente de Azure AI para crear un agente que pueda ayudar a responder preguntas sobre la información de los archivos de Azure Blob Storage.
Requisitos previos
Complete la configuración del agente estándar.
Asegúrese de que tiene el rol Colaborador de datos de Storage Blob en la cuenta de almacenamiento del proyecto.
Asegúrese de que tiene el rol Desarrollador de Azure AI en el proyecto.
Importante
La configuración del agente estándar solo admite la búsqueda de archivos mediante Blob Storage.
Paso 1: Creación de un cliente de proyecto
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"]
)
Paso 2: Carga de archivos locales en el contenedor de Azure Blob Storage del proyecto
Cargue el archivo local en el contenedor de Azure Blob Storage del proyecto. Esta es la misma cuenta de almacenamiento que ha conectado al agente durante la configuración. Al crear agentes adicionales en el mismo proyecto, puede reutilizar los URI de recursos de los archivos cargados previamente que necesiten esos agentes. Esto significa que no tiene que cargar el mismo archivo repetidamente, ya que los URI de recursos permiten hacer referencia a los archivos directamente.
A continuación, cree un almacén de vectores mediante asset_uri, que es la ubicación del archivo en el almacén de datos del proyecto.
# 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}")
Paso 3: Creación de un agente con acceso a la herramienta de búsqueda de archivos
# 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}")
Paso 4: Creación del segundo almacén de vectores mediante el archivo cargado anteriormente
Ahora, cree un segundo almacén de vectores mediante el archivo cargado anteriormente. El uso del objeto asset_uri de un archivo ya en Azure Blob Storage es útil si tiene varios agentes que necesitan acceso a los mismos archivos, ya que elimina la necesidad de cargar el mismo archivo varias veces.
# 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}")
Paso 5: Creación de un segundo agente con acceso a la herramienta de búsqueda de archivos
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}")
Tipos de archivo admitidos
Nota:
Para los tipos text/MIME, la codificación debe ser utf-8, utf-16 o ASCII.
| Formato de archivo | Tipo 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 |
Creación de almacenes vectoriales y adición de archivos
Agregar archivos a almacenes vectoriales es una operación asincrónica. Para asegurarse de que la operación está completa, se recomienda usar los asistentes "crear y sondear" en nuestros SDK oficiales. Si no usa los SDK, puede recuperar el objeto vector_store y supervisar su propiedad file_counts para ver el resultado de la operación de ingesta de archivos.
Los archivos también se pueden agregar a un almacén de vectores después de crearlos mediante la creación de archivos de almacén vectorial.
# 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}")
Como alternativa, puede agregar varios archivos a un almacén de vectores mediante la creación de lotes de hasta 500 archivos.
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]
)
Configuración básica del agente: eliminación de archivos de almacenes de vectores
Estos archivos se pueden quitar de un almacén de vectores mediante:
- Eliminar el objeto de archivo de almacén de vectores o,
- La eliminación del objeto de archivo subyacente (que quita el archivo de todas las configuraciones de vector_store y code_interpreter de todos los agentes y subprocesos de la organización).
El tamaño máximo de archivo es de 512 MB. Cada archivo no debe contener más de 5 000 000 tokens por archivo (calculado automáticamente al adjuntar un archivo).
Eliminación del almacén de vectores
Puede quitar un almacén de vectores de la herramienta de búsqueda de archivos.
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}")
Eliminación de los almacenes de vectores
project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")
Administración de costos con directivas de expiración
En la configuración básica del agente, la herramienta file_search usa el objeto vector_stores como recurso y se le factura en función del tamaño de los objetos vector_store creados. El tamaño del objeto de almacén de vectores es la suma de todos los fragmentos analizados de los archivos y sus incrustaciones correspondientes.
Para ayudarle a administrar los costos asociados a estos objetos vector_store, hemos agregado compatibilidad con las directivas de expiración en el objeto vector_store. Puede establecer estas directivas al crear o actualizar el objeto 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
}
)
Los almacenes de vectores de subprocesos tienen directivas de expiración predeterminadas
Los almacenes de vectores creados mediante asistentes de subprocesos (como tool_resources.file_search.vector_stores en subprocesos o message.attachments en mensajes) tienen una directiva de expiración predeterminada de siete días después de que estuvieran activas por última vez (definidas como la última vez que el almacén de vectores formaba parte de una ejecución).
Cuando un almacén de vectores expira, las ejecuciones en ese subproceso producen un error. Para corregirlo, puede volver a crear un nuevo objeto vector_store con los mismos archivos y volver a adjuntarlo al subproceso.