Hulpprogramma voor het zoeken van bestanden in Azure OpenAI-assistenten (preview)

Bestandszoekopdrachten vergroot de Assistent met kennis van buiten het model, zoals eigendoms- productinfromatie of documenten die door uw gebruikers worden verstrekt. OpenAI parseert en chunks uw documenten automatisch, maakt en slaat de insluitingen op en gebruikt zowel vector- als sleutelwoordzoekopdrachten om relevante inhoud op te halen om gebruikersquery's te beantwoorden.

Belangrijk

• Bestandszoekopdrachten hebben extra kosten buiten de kosten op basis van tokens voor Azure OpenAI-gebruik.

Notitie

• Bestanden zoeken kan maximaal 10.000 bestanden per assistent opnemen - 500 keer meer dan voorheen. Het is snel, ondersteunt parallelle query's via zoekopdrachten met meerdere threads en biedt uitgebreide herrankering en herschrijven van query's.
  • Vectoropslag is een nieuw object in de API. Zodra een bestand is toegevoegd aan een vectoropslag, wordt het automatisch geparseerd, gesegmenteerd en ingesloten, zodat het kan worden doorzocht. Vectoropslag kunnen worden gebruikt voor assistenten en threads, waardoor bestandsbeheer en facturering worden vereenvoudigd.
• We hebben ondersteuning toegevoegd voor de tool_choice parameter die kan worden gebruikt om het gebruik van een specifiek hulpprogramma (zoals het zoeken van bestanden, code-interpreter of een functie) in een bepaalde uitvoering af te dwingen.

Ondersteuning voor zoeken in bestanden

Ondersteunde regio’s

Zoeken naar bestanden is beschikbaar in regio's die assistenten ondersteunen.

API-versie

• 2024-05-01-preview

Ondersteunde bestandstypen

Notitie

Voor tekst-/MIME-typen moet de codering utf-8, utf-16 of ASCII zijn.

File format	MIME-type
c.	tekst/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	toepassing/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	tekst/x-tex
.txt	text/plain
.Css	text/css
.js	text/javascript
.Sh	application/x-sh
.Ts	toepassing/typescript

Bestanden zoeken inschakelen

Python 1.x

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

REST

Notitie

Bij Azure OpenAI is voor de parameter de naam van de model modelimplementatie vereist. Als de naam van uw modelimplementatie anders is dan de naam van het onderliggende model, past u de code aan. "model": "{your-custom-model-deployment-name}"

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

Bestanden uploaden voor het zoeken naar bestanden

Voor toegang tot uw bestanden gebruikt het hulpprogramma voor het zoeken van bestanden het vectorarchiefobject. Upload uw bestanden en maak een vectorarchief om ze te bevatten. Zodra het vectorarchief is gemaakt, moet u de status ervan controleren totdat alle bestanden de status hebben in_progress bereikt om ervoor te zorgen dat alle inhoud is verwerkt. De SDK biedt helpers voor het uploaden en peilen.

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)

De assistent bijwerken om het nieuwe vectorarchief te gebruiken

Als u de bestanden toegankelijk wilt maken voor uw assistent, werkt u de assistent tool_resources bij met de nieuwe vector_store id.

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

Een thread maken

U kunt ook bestanden toevoegen als berichtbijlagen in uw thread. Als u dit doet, wordt er nog een vector_store gekoppeld aan de thread gemaakt, of als er al een vectorarchief aan deze thread is gekoppeld, voegt u de nieuwe bestanden toe aan het bestaande threadvectorarchief. Wanneer u een run op deze thread maakt, wordt met het hulpprogramma voor het zoeken van bestanden zowel de vector_store query uitgevoerd vanuit uw assistent als op de vector_store thread.

# 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)

Vectorarchieven worden gemaakt met behulp van berichtbijlagen met een standaardverloopbeleid van zeven dagen nadat ze voor het laatst actief waren (gedefinieerd als de laatste keer dat het vectorarchief deel uitmaakte van een uitvoering). Deze standaardwaarde bestaat om u te helpen bij het beheren van de kosten voor vectoropslag. U kunt dit verloopbeleid op elk gewenst moment overschrijven.

Een uitvoering maken en de uitvoer controleren

Maak een run en kijk of het model gebruikmaakt van het hulpprogramma voor het zoeken van bestanden om een antwoord te geven op de vraag van de gebruiker.

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

Hoe het werkt

Het hulpprogramma voor het zoeken van bestanden implementeert verschillende aanbevolen procedures voor het ophalen van bestanden, zodat u de juiste gegevens uit uw bestanden kunt extraheren en de antwoorden van het model kunt uitbreiden. Het hulpprogramma file_search:

• Hiermee worden gebruikersquery's herschreven om ze te optimaliseren voor zoekopdrachten.
• Hiermee worden complexe gebruikersquery's opgesplitst in meerdere zoekopdrachten die parallel kunnen worden uitgevoerd.
• Voert zowel trefwoorden als semantische zoekopdrachten uit in zowel assistent- als threadvectorarchieven.
• Hiermee worden zoekresultaten opnieuw geherrankerd om de meest relevante resultaten te kiezen voordat het uiteindelijke antwoord wordt gegenereerd.
• Het hulpprogramma voor het zoeken van bestanden gebruikt standaard de volgende instellingen:
  • Segmentgrootte: 800 tokens
  • Segment overlap: 400 tokens
  • Insluitmodel: tekst-insluiten-3-groot bij 256 dimensies
  • Maximum aantal segmenten toegevoegd aan context: 20

Vectorarchieven

Vector Store-objecten geven het hulpprogramma voor het zoeken van bestanden de mogelijkheid om uw bestanden te doorzoeken. Als u een bestand toevoegt aan een vectorarchief, worden het bestand automatisch geparseerd, segmenten, ingesloten en opgeslagen in een vectordatabase die geschikt is voor trefwoorden en semantische zoekopdrachten. Elk vectorarchief kan maximaal 10.000 bestanden bevatten. Vectorarchieven kunnen worden gekoppeld aan zowel assistenten als threads. Op dit moment kunt u maximaal één vectorarchief koppelen aan een assistent en maximaal één vectorarchief aan een thread.

Vectorarchieven maken en bestanden toevoegen

U kunt een vectorarchief maken en er bestanden aan toevoegen in één API-aanroep:

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

Het toevoegen van bestanden aan vectorarchieven is een asynchrone bewerking. Om ervoor te zorgen dat de bewerking is voltooid, raden we u aan de helpers 'maken en peilen' te gebruiken in onze officiële SDK's. Als u de SDK's niet gebruikt, kunt u het object ophalen en de vector_store eigenschap ervan bewaken file_counts om het resultaat van de bestandsopnamebewerking te zien.

Bestanden kunnen ook worden toegevoegd aan een vectoropslag nadat deze is gemaakt door vectoropslagbestanden te maken.

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

U kunt ook verschillende bestanden toevoegen aan een vectorarchief door batches van maximaal 500 bestanden te maken.

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

Op dezelfde manier kunnen deze bestanden worden verwijderd uit een vectoropslag door:

• Het vectoropslag bestandsobject te verwijderen of,
• Door het onderliggende bestandsobject te verwijderen (waarmee het bestand wordt verwijderd uit alle vector_store en code_interpreter configuraties voor alle assistenten en threads in uw organisatie)

De maximale bestandsgrootte is 512 MB. Elk bestand mag niet meer dan 5.000.000 tokens per bestand bevatten (automatisch berekend wanneer u een bestand bijvoegt).

Vectorarchieven koppelen

U kunt vectorarchieven aan uw assistent of thread koppelen met behulp van de parameter 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"]
    }
  }
)

U kunt ook een vectorarchief koppelen aan threads of assistenten nadat ze zijn gemaakt door ze bij te werken met de rechterkant tool_resources.

Gereedheid voor vectoropslag garanderen voordat er uitvoeringen worden gemaakt

We raden u ten zeerste aan ervoor te zorgen dat alle bestanden in een vector_store volledig worden verwerkt voordat u een uitvoering maakt. Dit zorgt ervoor dat alle gegevens in uw vectorarchief doorzoekbaar zijn. U kunt controleren op gereedheid voor vectoropslag met behulp van de polling-helpers in de SDK's of door het vector_store object handmatig te peilen om ervoor te zorgen dat de status is voltooid.

Als terugval is er een maximale wachttijd van 60 seconden in het uitvoeringsobject wanneer het vectorarchief van de thread bestanden bevat die nog worden verwerkt. Dit is om ervoor te zorgen dat bestanden die uw gebruikers uploaden in een thread een volledig doorzoekbaar zijn voordat de uitvoering wordt uitgevoerd. Deze terugvalwacht is niet van toepassing op het vectorarchief van de assistent.

Kosten beheren met verloopbeleid

Het file_search hulpprogramma gebruikt het vector_stores object als resource en u wordt gefactureerd op basis van de grootte van de vector_store objecten die zijn gemaakt. De grootte van het vectorarchiefobject is de som van alle geparseerde segmenten uit uw bestanden en de bijbehorende insluitingen.

Om u te helpen bij het beheren van de kosten die zijn gekoppeld aan deze vector_store-objecten, hebben we ondersteuning toegevoegd voor verloopbeleid in het vector_store object. U kunt deze beleidsregels instellen bij het maken of bijwerken van het vector_store object.

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

Thread vector stores hebben standaard verloopbeleid

Vectorarchieven die zijn gemaakt met thread-helpers (zoals tool_resources.file_search.vector_stores in threads of message.attachments in berichten) hebben een standaardverloopbeleid van zeven dagen nadat ze voor het laatst actief waren (gedefinieerd als de laatste keer dat het vectorarchief deel uitmaakte van een uitvoering).

Wanneer een vectorarchief verloopt, mislukt de uitvoering op die thread. U kunt dit oplossen door een nieuwe vector_store opnieuw te maken met dezelfde bestanden en deze opnieuw aan de thread te koppelen.

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]
    )