Справочник по API помощников (предварительная версия)
Примечание.
- Поиск по файлам может получать до 10 000 файлов на помощника — 500 раз больше, чем раньше. Это быстро, поддерживает параллельные запросы с помощью многопоточных поисковых запросов, а также функции расширенного перерасписывания и перезаписи запросов.
- Векторное хранилище — это новый объект в API. После добавления файла в векторное хранилище он автоматически анализируется, блокируется и внедряется, подготавливается к поиску. Векторные хранилища можно использовать между помощниками и потоками, упрощая управление файлами и выставление счетов.
- Мы добавили поддержку
tool_choiceпараметра, который можно использовать для принудительного использования определенного средства (например, поиска файлов, интерпретатора кода или функции) в определенном запуске.
В этой статье приведена справочная документация по Python и REST для нового API Помощников (предварительная версия). Дополнительные пошаговые инструкции приведены в руководстве по началу работы.
Создание помощника
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Создайте помощника с моделью и инструкциями.
Текст запроса
| Имя. | Type | Обязательно | Описание |
|---|---|---|---|
| модель | строка | Обязательное поле | Имя развертывания модели для используемой модели. |
| name | строка или null | Необязательно | Имя помощника. Максимальная длина составляет 256 символов. |
| описание | строка или null | Необязательно | Описание помощника. Максимальная длина — 512 символов. |
| инструкции | строка или null | Необязательно | Системные инструкции, которые использует помощник. Максимальная длина — 256 000 символов. |
| средства | array | Необязательно | По умолчанию — []. Список инструментов, включенных помощником. На помощника может быть не более 128 инструментов. В настоящее время средства могут быть типами code_interpreterили function. Описание function может быть не более 1024 символов. |
| file_ids | array | Необязательно | По умолчанию — []. Список идентификаторов файлов, подключенных к этому помощнику. К помощнику может быть подключено не более 20 файлов. Файлы упорядочены по дате создания в порядке возрастания. |
| metadata | map | Необязательно | Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту. Это может быть полезно для хранения дополнительных сведений об объекте в структурированном формате. Ключи могут содержать не более 64 символов, а значения могут содержать не более 512 символов. |
| Температура | число или null | Необязательно | По умолчанию равен 1. Определяет, какая температура выборки используется в диапазоне от 0 до 2. Более высокие значения, такие как 0,8, делают выходные данные более случайными, а более низкие значения, такие как 0,2, делают его более ориентированным и детерминированным. |
| top_p | число или null | Необязательно | По умолчанию равен 1. Альтернативой выборке с температурой является так называемая выборка ядра, где модель рассматривает результаты маркеров с top_p всего массива значений вероятности. Таким образом, 0,1 означает, что учитываются только маркеры, входящие в верхние 10% массива значений вероятности. Как правило, мы рекомендуем изменить либо это значение, либо температуру, но не оба. |
| response_format | Строка или объект | Необязательно | Указывает формат, который модель должна выводить. Совместим с GPT-4 Turbo и всеми моделями GPT-3.5 Turbo с gpt-3.5-turbo-1106. Установка этого параметра в { "type": "json_object" } режиме JSON, который гарантирует, что модель создает сообщение является допустимым JSON. Важно отметить, что при использовании режима JSON необходимо также указать модели создавать JSON самостоятельно с помощью системного или пользовательского сообщения. Без этой инструкции модель может создать поток пробелов, пока поколение не достигнет предела маркера, в результате чего длительный и, казалось бы, "застрял" запрос. Кроме того, содержимое сообщения может быть частично отрезано при использовании finish_reason="length", что указывает на превышение поколения max_tokens или беседа превысила максимальную длину контекста. |
Возвраты
Пример запроса помощника по созданию
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(
instructions="You are an AI assistant that can write code to help answer math questions",
model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name.
tools=[{"type": "code_interpreter"}]
)
Создание файла помощника
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Создайте файл помощника, подключив его File к объекту assistant.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
assistant_id |
строка | Обязательное поле | Идентификатор помощника, к которому должен быть присоединен файл. |
Текст запроса
| Имя. | Type | Обязательно | Описание |
|---|---|---|---|
| file_id | строка | Обязательное поле | Идентификатор файла (с назначением ="помощники"), который должен использовать помощник. Полезно для таких средств, как code_interpreter, которые могут получить доступ к файлам. |
Возвраты
Объект файла помощника.
Пример запроса на создание файла помощника
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_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Список помощников
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Возвращает список всех помощников.
параметры запроса.
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
limit |
integer | Необязательно | Ограничение количества возвращаемых объектов. Ограничение может быть от 1 до 100, а значение по умолчанию — 20. |
order |
строка | Необязательно. Значения по умолчанию для desc | Сортировка по created_at метке времени объектов. asc для возрастания порядка и desc для убывающего порядка. |
after |
строка | Необязательно | Курсор для использования в разбиении на страницы. after — это идентификатор объекта, определяющий место в списке. Например, если вы делаете запрос списка и получаете 100 объектов, заканчивая obj_foo, последующий вызов может включать after=obj_foo, чтобы получить следующую страницу списка. |
before |
строка | Необязательно | Курсор для использования в разбиении на страницы. before — это идентификатор объекта, определяющий место в списке. Например, если вы делаете запрос списка и получаете 100 объектов, заканчивая obj_foo, последующий вызов может включать до=obj_foo, чтобы получить предыдущую страницу списка. |
Возвраты
Примеры помощников по списку
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")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
Перечисление файлов помощника
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Возвращает список файлов помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
| assistant_id | строка | Обязательное поле | Идентификатор помощника, к которому принадлежит файл. |
параметры запроса.
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
limit |
integer | Необязательно | Ограничение количества возвращаемых объектов. Ограничение может быть от 1 до 100, а значение по умолчанию — 20. |
order |
строка | Необязательно. Значения по умолчанию для desc | Сортировка по created_at метке времени объектов. asc для возрастания порядка и desc для убывающего порядка. |
after |
строка | Необязательно | Курсор для использования в разбиении на страницы. after — это идентификатор объекта, определяющий место в списке. Например, если вы делаете запрос списка и получаете 100 объектов, заканчивая obj_foo, последующий вызов может включать after=obj_foo, чтобы получить следующую страницу списка. |
before |
строка | Необязательно | Курсор для использования в разбиении на страницы. before — это идентификатор объекта, определяющий место в списке. Например, если вы делаете запрос списка и получаете 100 объектов, заканчивая obj_foo, последующий вызов может включать до=obj_foo, чтобы получить предыдущую страницу списка. |
Возвраты
Список объектов файлов помощника
Примеры файлов помощника по списку
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_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
Получение помощника
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Извлекает помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
assistant_id |
строка | Обязательное поле | Идентификатор извлекаемого помощника. |
Возвраты
Объект помощника , соответствующий указанному идентификатору.
Пример помощника по извлечению
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
Получение файла помощника
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Извлекает файл помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
| assistant_id | строка | Обязательное поле | Идентификатор помощника, к которому принадлежит файл. |
| file_id | строка | Обязательное поле | Идентификатор файла, который мы получаем |
Возвраты
Объект файла помощника, соответствующий указанному идентификатору
Пример получения файла помощника
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Изменение помощника
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Изменяет помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
| assistant_id | строка | Обязательное поле | Идентификатор помощника, к которому принадлежит файл. |
Текст запроса
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
model |
Необязательно | Имя развертывания модели для используемой модели. | |
name |
строка или null | Необязательно | Имя помощника. Максимальная длина составляет 256 символов. |
description |
строка или null | Необязательно | Описание помощника. Максимальная длина — 512 символов. |
instructions |
строка или null | Необязательно | Системные инструкции, которые использует помощник. Максимальная длина — 32768 символов. |
tools |
array | Необязательно | По умолчанию — []. Список инструментов, включенных помощником. На помощника может быть не более 128 инструментов. Средства могут быть типами code_interpreter или функцией. Описание function может быть не более 1024 символов. |
file_ids |
array | Необязательно | По умолчанию — []. Список идентификаторов файлов, подключенных к этому помощнику. К помощнику может быть подключено не более 20 файлов. Файлы упорядочены по дате создания в порядке возрастания. Если файл был ранее присоединен к списку, но не отображается в списке, он будет удален из помощника. |
metadata |
map | Необязательно | Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту. Это может быть полезно для хранения дополнительных сведений об объекте в структурированном формате. Ключи могут содержать не более 64 символов, а значения могут содержать не более 512 символов. |
Возвраты
Измененный объект помощника.
Пример помощника по изменению
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_updated_assistant = client.beta.assistants.update(
"asst_abc123",
instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
name="HR Helper",
tools=[{"type": "code-interpreter"}],
model="gpt-4", #model = model deployment name
file_ids=["assistant-abc123", "assistant-abc456"],
)
print(my_updated_assistant)
Удаление помощника
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview
Удаление помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
assistant_id |
строка | Обязательное поле | Идентификатор помощника, к которому принадлежит файл. |
Возвраты
Состояние удаления.
Пример помощника по удалению
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
Удаление файла помощника
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Удалите файл помощника.
Параметры пути
| Параметр | Type | Обязательно | Описание |
|---|---|---|---|
assistant_id |
строка | Обязательное поле | Идентификатор помощника, к которому принадлежит файл. |
file_id |
строка | Обязательное поле | Идентификатор файла для удаления |
Возвраты
Состояние удаления файла
Пример файла помощника по удалению
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(deleted_assistant_file)
Справочник по API отправки файлов
Помощники используют тот же API для отправки файлов, что и для точной настройки. При отправке файла необходимо указать соответствующее значение для параметра назначения.
Объект Assistant
| Поле | Тип | Описание: |
|---|---|---|
id |
строка | Идентификатор, на который можно ссылаться в конечных точках API. |
object |
строка | Тип объекта, который всегда является помощником. |
created_at |
integer | Метка времени Unix (в секундах) для момента создания помощника. |
name |
строка или null | Имя помощника. Максимальная длина составляет 256 символов. |
description |
строка или null | Описание помощника. Максимальная длина — 512 символов. |
model |
строка | Имя используемого имени развертывания модели. |
instructions |
строка или null | Системные инструкции, которые использует помощник. Максимальная длина — 32768 символов. |
tools |
array | Список инструментов, включенных помощником. На помощника может быть не более 128 инструментов. Средства могут быть типами code_interpreter или функцией. Описание function может быть не более 1024 символов. |
file_ids |
array | Список идентификаторов файлов, подключенных к этому помощнику. К помощнику может быть подключено не более 20 файлов. Файлы упорядочены по дате создания в порядке возрастания. |
metadata |
map | Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту. Это может быть полезно для хранения дополнительных сведений об объекте в структурированном формате. Ключи могут содержать не более 64 символов, а значения могут содержать не более 512 символов. |
Объект файла помощника
| Поле | Тип | Описание: |
|---|---|---|
id |
строка | Идентификатор, на который можно ссылаться в конечных точках API. |
object |
строка | Тип объекта, который всегда является assistant.file |
created_at |
integer | Метка времени Unix (в секундах) для создания файла помощника. |
assistant_id |
строка | Идентификатор помощника, к которому присоединен файл. |
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по