Справочник по API помощников (предварительная версия)

Статья
09/27/2024

Примечание.

Поиск по файлам может получать до 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 символов.
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` или беседа превысила максимальную длину контекста.
tool_resources	объект	Необязательно	Набор ресурсов, используемых средствами помощника. Ресурсы относятся к типу инструмента. Например, для `code_interpreter` средства требуется список идентификаторов файлов, а для `file_search` этого средства требуется список идентификаторов векторного хранилища.

Возвраты

Объект помощника.

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-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"}]
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

Список помощников

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, чтобы получить предыдущую страницу списка.

Возвраты

Список объектов помощника

Примеры помощников по списку

Python 1.x
REST

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

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-08-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

Получение помощника

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Извлекает помощника.

Параметры пути

Параметр	Type	Обязательно	Описание
`assistant_id`	строка	Обязательное поле	Идентификатор извлекаемого помощника.

Возвраты

Объект помощника , соответствующий указанному идентификатору.

Пример помощника по извлечению

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-08-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

Изменение помощника

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Изменяет помощника.

Параметры пути

Параметр	Type	Обязательно	Описание
assistant_id	строка	Обязательное поле	Идентификатор помощника, к которому принадлежит файл.

Текст запроса

Параметр	Type	Обязательно	Описание
`model`		Необязательно	Имя развертывания модели для используемой модели.
`name`	строка или null	Необязательно	Имя помощника. Максимальная длина составляет 256 символов.
`description`	строка или null	Необязательно	Описание помощника. Максимальная длина — 512 символов.
`instructions`	строка или null	Необязательно	Системные инструкции, которые использует помощник. Максимальная длина — 32768 символов.
`tools`	array	Необязательно	По умолчанию — []. Список инструментов, включенных помощником. На помощника может быть не более 128 инструментов. Средства могут быть типами code_interpreter или функцией. Описание `function` может быть не более 1024 символов.
`metadata`	map	Необязательно	Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту. Это может быть полезно для хранения дополнительных сведений об объекте в структурированном формате. Ключи могут содержать не более 64 символов, а значения могут содержать не более 512 символов.
`temperature`	число или 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` или беседа превысила максимальную длину контекста.
`tool_resources`	объект	Необязательно	Набор ресурсов, используемых средствами помощника. Ресурсы относятся к типу инструмента. Например, для `code_interpreter` средства требуется список идентификаторов файлов, а для `file_search` этого средства требуется список идентификаторов векторного хранилища.

Возвраты

Измененный объект помощника.

Пример помощника по изменению

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-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
)

print(my_updated_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-08-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4"
    }'

Удаление помощника

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Удаление помощника.

Параметры пути

Параметр	Type	Обязательно	Описание
`assistant_id`	строка	Обязательное поле	Идентификатор помощника, к которому принадлежит файл.

Возвраты

Состояние удаления.

Пример помощника по удалению

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-08-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

Справочник по 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 символов.
`metadata`	map	Набор из 16 пар "ключ-значение", которые могут быть присоединены к объекту. Это может быть полезно для хранения дополнительных сведений об объекте в структурированном формате. Ключи могут содержать не более 64 символов, а значения могут содержать не более 512 символов.
`temperature`	число или 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` или беседа превысила максимальную длину контекста.
`tool_resources`	объект	Набор ресурсов, используемых средствами помощника. Ресурсы относятся к типу инструмента. Например, для `code_interpreter` средства требуется список идентификаторов файлов, а для `file_search` этого средства требуется список идентификаторов векторного хранилища.

Поделиться через

Справочник по API помощников (предварительная версия)

Создание помощника

Текст запроса

Возвраты

Пример запроса помощника по созданию

Список помощников

Возвраты

Примеры помощников по списку

Получение помощника

Пример помощника по извлечению

Изменение помощника

Пример помощника по изменению

Удаление помощника

Пример помощника по удалению

Справочник по API отправки файлов

Объект Assistant

Обратная связь

Дополнительные ресурсы