Azure OpenAI Assistants herramienta de búsqueda de archivos (versión preliminar clásico)

Solo se aplica a:Portal de Foundry (clásico). Este artículo no está disponible para el nuevo portal de Foundry. Obtenga más información sobre el nuevo portal.

La búsqueda de archivos realza el Asistente con conocimientos externos a su modelo, como la información propietaria de productos o los documentos proporcionados por los usuarios. OpenAI analiza y fragmenta automáticamente los documentos, crea y almacena las incrustaciones y usa la búsqueda de vectores y palabras clave para recuperar contenido relevante para responder a las consultas del usuario.

Compatibilidad con la búsqueda de archivos

Regiones compatibles

La búsqueda de archivos está disponible en regiones que admiten asistentes.

Versión de API

• A partir de 2024-05-01-preview

Tipos de archivo admitidos

Habilitación de la búsqueda de archivos

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  name="Financial Analyst Assistant",
  instructions="You are an expert financial analyst. Use your knowledge base to answer questions about audited financial statements.",
  model="gpt-4-turbo",
  tools=[{"type": "file_search"}],
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Financial Analyst Assistant",
    "instructions": "You are an expert financial analyst. Use your knowledge base to answer questions about audited financial statements.",
    "tools": [{"type": "file_search"}],
    "model": "gpt-4-turbo"
  }'

Carga de archivos para la búsqueda de archivos

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 para contenerlos. Una vez creado el almacén de vectores, debe sondear su estado hasta que todos los archivos estén fuera del in_progress estado para asegurarse de que todo el contenido haya terminado de procesarse. El SDK proporciona asistentes para cargar y sondear.

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

# Create a vector store called "Financial Statements"
vector_store = client.beta.vector_stores.create(name="Financial Statements")
 
# Ready the files for upload to OpenAI
file_paths = ["mydirectory/myfile1.pdf", "mydirectory/myfile2.txt"]
file_streams = [open(path, "rb") for path in file_paths]
 
# Use the upload and poll SDK helper to upload the files, add them to the vector store,
# and poll the status of the file batch for completion.
file_batch = client.beta.vector_stores.file_batches.upload_and_poll(
  vector_store_id=vector_store.id, files=file_streams
)
 
# You can print the status and the file counts of the batch to see the result of this operation.
print(file_batch.status)
print(file_batch.file_counts)

Actualizar el asistente para usar el nuevo almacén de vectores

Para que los archivos sean accesibles para el asistente, actualice el tool_resources del asistente con el nuevo vector_store ID.

assistant = client.beta.assistants.update(
  assistant_id=assistant.id,
  tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

Crear un hilo

También puede adjuntar archivos como datos adjuntos de mensajes en el subproceso. Al hacerlo, se creará otro vector_store asociado al subproceso o, si ya hay un almacén de vectores adjunto a este subproceso, adjunte 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 consultará el vector_store desde el asistente y el vector_store en el subproceso.

# Upload the user provided file to OpenAI
message_file = client.files.create(
  file=open("mydirectory/myfile.pdf", "rb"), purpose="assistants"
)
 
# Create a thread and attach the file to the message
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "How many company shares were outstanding last quarter?",
      # Attach the new file to the message.
      "attachments": [
        { "file_id": message_file.id, "tools": [{"type": "file_search"}] }
      ],
    }
  ]
)
 
# The thread now has a vector store with that file in its tool resources.
print(thread.tool_resources.file_search)

Los almacenes de vectores se crean mediante datos adjuntos de mensajes que 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). Este valor predeterminado existe para ayudarle a administrar los costos de almacenamiento de vectores. Puede invalidar estas directivas de expiración en cualquier momento.

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.

from typing_extensions import override
from openai import AssistantEventHandler, OpenAI
 
client = OpenAI()
 
class EventHandler(AssistantEventHandler):
    @override
    def on_text_created(self, text) -> None:
        print(f"\nassistant > ", end="", flush=True)

    @override
    def on_tool_call_created(self, tool_call):
        print(f"\nassistant > {tool_call.type}\n", flush=True)

    @override
    def on_message_done(self, message) -> None:
        # print a citation to the file searched
        message_content = message.content[0].text
        annotations = message_content.annotations
        citations = []
        for index, annotation in enumerate(annotations):
            message_content.value = message_content.value.replace(
                annotation.text, f"[{index}]"
            )
            if file_citation := getattr(annotation, "file_citation", None):
                cited_file = client.files.retrieve(file_citation.file_id)
                citations.append(f"[{index}] {cited_file.filename}")

        print(message_content.value)
        print("\n".join(citations))

# Then, we use the stream SDK helper
# with the EventHandler class to create the Run
# and stream the response.

with client.beta.threads.runs.stream(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
    event_handler=EventHandler(),
) as stream:
    stream.until_done()

Cómo funciona

La herramienta de búsqueda de archivos implementa varios procedimientos recomendados de recuperación de datos para ayudarle a extraer los datos adecuados de los archivos y mejorar las respuestas del modelo. La herramienta file_search:

• 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 palabras clave en almacenes de vectores de subprocesos y asistentes.
• Reordena los resultados de búsqueda para seleccionar 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 analiza, divide en fragmentos, incrusta y almacena el archivo en una base de datos vectorial capaz de realizar búsquedas por palabra clave y semánticas. Cada almacén de vectores puede contener hasta 10 000 archivos. Los almacenes de vectores se pueden adjuntar tanto a asistentes como a subprocesos. Actualmente, puede adjuntar como máximo un almacén de vectores a un asistente y, como máximo, un almacén de vectores a un subproceso.

Creación de almacenes vectoriales y adición de archivos

Puede crear un almacén de vectores y agregar archivos a él en una sola llamada API:

vector_store = client.beta.vector_stores.create(
  name="Product Documentation",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5']
)

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 vector_store objeto y supervisar su file_counts propiedad 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.

file = client.beta.vector_stores.files.create_and_poll(
  vector_store_id="vs_abc123",
  file_id="file-abc123"
)

Como alternativa, puede agregar varios archivos a un almacén de vectores mediante la creación de lotes de hasta 500 archivos.

batch = client.beta.vector_stores.file_batches.create_and_poll(
  vector_store_id="vs_abc123",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5']
)

Del mismo modo, estos archivos se pueden quitar de un almacén de vectores mediante:

• Eliminar el objeto de archivo del almacén de vectores o,
• Al eliminar un objeto de archivo subyacente (lo que elimina el archivo de todas las configuraciones de vector_store y code_interpreter en todos los asistentes y subprocesos dentro de su organización)

El tamaño máximo de archivo es de 512 MB. Cada archivo no debe contener más de 5000 000 tokens por archivo (calculado automáticamente al adjuntar un archivo).

Adjuntar almacenes vectoriales

Puede adjuntar almacenes de vectores a su Asistente o Subproceso mediante el parámetro tool_resources.

assistant = client.beta.assistants.create(
  instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",
  model="gpt-4-turbo",
  tools=[{"type": "file_search"}],
  tool_resources={
    "file_search": {
      "vector_store_ids": ["vs_1"]
    }
  }
)

thread = client.beta.threads.create(
  messages=[ { "role": "user", "content": "How do I cancel my subscription?"} ],
  tool_resources={
    "file_search": {
      "vector_store_ids": ["vs_2"]
    }
  }
)

También puede adjuntar un almacén de vectores a subprocesos o asistentes después de crearlos actualizando con el derecho tool_resources.

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 en los SDK o sondeando manualmente el objeto vector_store para asegurarse de que el estado se ha completado.

Como medida de respaldo, hay una espera máxima de 60 segundos en el objeto de ejecución cuando el almacenamiento 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 asistente.

Administración de costos con políticas de expiración

La file_search herramienta usa el vector_stores objeto como recurso y se le facturará 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 vector_store objeto . Puede establecer estas directivas al crear o actualizar el vector_store objeto.

vector_store = client.beta.vector_stores.create_and_poll(
  name="Product Documentation",
  file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5'],
  expires_after={
	  "anchor": "last_active_at",
	  "days": 7
  }
)

Los almacenes de vectores de hilos 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 fueran activos por última vez (definido como la última vez que el almacén de vectores formaba parte de una ejecución).

Cuando un almacenamiento de vectores expira, las ejecuciones en ese subproceso fallarán. Para corregirlo, puede volver a crear un nuevo vector_store con los mismos archivos y volver a adjuntarlo al subproceso.

all_files = list(client.beta.vector_stores.files.list("vs_expired"))

vector_store = client.beta.vector_stores.create(name="rag-store")
client.beta.threads.update(
    "thread_abc123",
    tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)

for file_batch in chunked(all_files, 100):
    client.beta.vector_stores.file_batches.create_and_poll(
        vector_store_id=vector_store.id, file_ids=[file.id for file in file_batch]
    )