Средство поиска файлов Azure OpenAI Assistants (предварительная версия)

Функция поиска в файлах расширяет базу помощника, добавляя знания из-за пределов его модели, например сведения о продуктах или информацию из документов, предоставляемых пользователями. OpenAI автоматически анализирует и сегментирует документы, создает и сохраняет векторные представления, а также использует поиск по векторам и ключевым словам для получения соответствующего содержимого для ответа на запросы пользователей.

Внимание

• При поиске со содержимому файлов взимается дополнительная плата за использование токенов Azure OpenAI.

Примечание.

• Поиск по файлам может получать до 10 000 файлов на помощника — 500 раз больше, чем раньше. Это быстрый процесс, который поддерживает параллельные многопоточные поисковые запросы, а также функции расширенного повторного ранжирования и перезаписи запросов.
  • Векторное хранилище — это новый объект в API. После добавления файла в векторное хранилище он автоматически анализируется, делится на блоки и кодируется в векторном представлении, чтобы подготовить к поиску по содержимому. Векторные хранилища можно использовать между разными помощниками и потоками, упрощая управление файлами и выставление счетов.
• Мы добавили поддержку tool_choice параметра, который можно использовать для принудительного использования определенного средства (например, поиска файлов, интерпретатора кода или функции) в определенном запуске.

Поддержка поиска файлов

Поддерживаемые регионы

Поиск файлов доступен в регионах , поддерживающих помощников.

Версия API

• 2024-05-01-preview

Поддерживаемые типы файлов

Примечание.

Для типов text/MIME кодировка должна быть либо utf-8, utf-16, либо ASCII.

File format	Тип 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.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

Включение поиска файлов

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

Примечание.

При использовании Azure OpenAI для model параметра требуется имя развертывания модели. Если имя развертывания модели отличается от имени базовой модели, то вы измените код на "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"
  }'

Отправка файлов для поиска файлов

Для доступа к файлам средство поиска файлов использует объект векторного хранилища. Отправьте файлы и создайте векторное хранилище для их хранения. После создания векторного хранилища необходимо провести опрос состояния до тех пор, пока все файлы не находятся в in_progress состоянии, чтобы убедиться, что все содержимое завершено. Пакет SDK предоставляет вспомогательные средства для отправки и опроса.

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)

Обновление помощника для использования нового векторного хранилища

Чтобы сделать файлы доступными для помощника, обновите помощника tool_resources с новым vector_store идентификатором.

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

Создание потока

Вы также можете вложить файлы в виде вложений сообщений в потоке. Это приведет к созданию другого vector_store связанного с потоком или, если к этому потоку уже подключено векторное хранилище, прикрепите новые файлы к существующему хранилищу векторов потоков. При создании запуска в этом потоке средство поиска файлов будет запрашивать как от помощника, так vector_store и vector_store от потока.

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

Хранилища векторов создаются с помощью вложений сообщений, которые имеют политику истечения срока действия по умолчанию в течение семи дней после последнего активного (определяется как последний раз, когда хранилище векторов было частью выполнения). Это значение по умолчанию позволяет управлять затратами на хранилище векторов. Эти политики истечения срока действия можно переопределить в любое время.

Создание выполнения и проверка выходных данных

Создайте запуск и обратите внимание, что модель использует средство поиска файлов для предоставления ответа на вопрос пользователя.

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

Принцип работы

Средство поиска файлов реализует несколько рекомендаций по извлечению из поля, которые помогут извлечь правильные данные из файлов и расширить ответы модели. Средство file_search:

• Перезаписывает запросы пользователей, чтобы оптимизировать их для поиска.
• Разбивает сложные запросы пользователей на несколько поисковых запросов, которые могут выполняться параллельно.
• Выполняет как ключевые слова, так и семантические поиски в хранилищах векторов помощника и потока.
• Повторно выбирает результаты поиска, чтобы выбрать наиболее релевантные, прежде чем создавать окончательный ответ.
• По умолчанию средство поиска файлов использует следующие параметры:
  • Размер блока: 800 токенов
  • Перекрытие блока: 400 маркеров
  • Модель внедрения: text-embedding-3-large на 256 измерениях
  • Максимальное количество блоков, добавленных в контекст: 20

Хранилища векторов

Объекты векторного хранилища предоставляют средству поиска файлов возможность поиска файлов. Добавление файла в векторное хранилище автоматически анализирует, блоки, внедряет и сохраняет файл в векторной базе данных, которая поддерживает как ключевое слово, так и семантический поиск. Каждое векторное хранилище может содержать до 10 000 файлов. Хранилища векторов можно подключить как к помощникам, так и к потокам. В настоящее время можно присоединить не более одного векторного хранилища к помощнику и по крайней мере одно хранилище векторов к потоку.

Создание векторных хранилищ и добавление файлов

Вы можете создать векторное хранилище и добавить в него файлы в одном вызове API:

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

Добавление файлов в векторные хранилища — это асинхронная операция. Чтобы убедиться, что операция завершена, рекомендуется использовать вспомогательные средства создания и опроса в наших официальных пакетах SDK. Если вы не используете пакеты SDK, вы можете получить vector_store объект и отслеживать его file_counts свойство, чтобы увидеть результат операции приема файлов.

Файлы также можно добавить в векторное хранилище после его создания путем создания файлов векторного хранилища.

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

Кроме того, можно добавить несколько файлов в векторное хранилище путем создания пакетов до 500 файлов.

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

Аналогичным образом эти файлы можно удалить из векторного хранилища следующим образом.

• Удаление объекта файла векторного хранилища или
• Удаление базового объекта файла (который удаляет файл из всех конфигураций vector_store и code_interpreter во всех помощниках и потоках в организации)

Максимальный размер файла — 512 МБ. Каждый файл должен содержать не более 5 000 000 токенов для каждого файла (вычисляется автоматически при вложении файла).

Присоединение хранилищ векторов

Вы можете присоединить векторные хранилища к помощнику или потоку с помощью параметра 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"]
    }
  }
)

Вы также можете подключить векторное хранилище к потокам или помощникам после их создания, обновив их право tool_resources.

Обеспечение готовности хранилища векторов перед созданием запусков

Мы настоятельно рекомендуем убедиться, что все файлы в vector_store полностью обрабатываются перед созданием запуска. Это гарантирует возможность поиска всех данных в хранилище векторов. Вы можете проверить готовность хранилища векторов с помощью вспомогательных средств опроса в пакетах SDK или вручную провести опрос vector_store объекта, чтобы убедиться, что состояние завершено.

В качестве резервной копии в объекте выполнения выполняется 60-секундное ожидание, когда хранилище векторов потока содержит файлы, которые по-прежнему обрабатываются. Это гарантирует, что все файлы, которые пользователи отправляют в поток, полностью доступный для поиска перед выполнением. Это резервное ожидание не применяется к хранилищу векторов помощника.

Управление затратами с помощью политик истечения срока действия

Средство file_search использует vector_stores объект в качестве ресурса, и вы будете выставляться на основе размера созданных vector_store объектов. Размер объекта векторного хранилища — это сумма всех проанализированных блоков из файлов и их соответствующих внедрения.

Чтобы помочь вам управлять затратами, связанными с этими объектами vector_store, мы добавили поддержку политик истечения срока действия в объекте vector_store . Эти политики можно задать при создании или обновлении vector_store объекта.

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

Хранилища векторов потоков имеют политики истечения срока действия по умолчанию

Хранилища векторов, созданные с помощью вспомогательных средств потоков (например tool_resources.file_search.vector_stores , в потоках или message.attachments сообщениях), имеют политику истечения срока действия по умолчанию в течение семи дней после последнего активного (определяется как последний раз, когда хранилище векторов было частью выполнения).

Когда срок действия хранилища векторов истекает, запуск в этом потоке завершится ошибкой. Чтобы устранить эту проблему, можно создать новую vector_store с теми же файлами и повторно подключить ее к потоку.

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