Руководство по API помощников OpenAI

1. Представление API OpenAI Assistants

1.1 Определение и цель Assistants API

API Assistants позволяет разработчикам создавать искусственных интеллектуальных помощников в рамках их собственных приложений. Путем определения пользовательских команд и выбора моделей помощники могут использовать модели, инструменты и знания для ответа на запросы пользователей. В настоящее время API Assistants поддерживает три типа инструментов: интерпретатор кода, поиск и вызов функций.

1.2 Применение API Assistants

API Assistants подходит для различных сценариев, требующих интерактивной поддержки искусственного интеллекта. Например:

Поддержка клиентов: Автоматически отвечайте на часто задаваемые вопросы, чтобы снизить нагрузку на службу поддержки клиентов.
Онлайн-образование: Отвечайте на вопросы студентов и обеспечивайте индивидуальную учебную поддержку.
Анализ данных: Анализируйте файлы данных, загруженные пользователями, генерируйте отчеты и визуализируйте графики.
Персонализированные рекомендации: Предоставляйте персонализированные предложения и услуги на основе исторических взаимодействий пользователей.

1.3 Основные концепции Assistants

Основные объекты API Assistants включают объекты Assistant, Thread и Message. Ниже приведены подробные введения в эти объекты и их функции:

Assistant

Объект Assistant построен на основе моделей OpenAI и может вызывать инструменты интеллектуального помощника. Вы можете настраивать инструкции Assistant, чтобы адаптировать его личность и функциональность. Например, вы можете создать Assistant с именем "Аналитик данных", который анализирует данные и создает графики с использованием инструмента "code_interpreter".

Thread

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

Message

Объект Message может быть создан пользователем или Assistant. Сообщения могут содержать текст, изображения и другие файлы. Сообщения хранятся в виде списка в Thread. В реальном использовании API разработчики могут добавлять пользовательские сообщения в Thread и вызывать ответ Assistant по мере необходимости.

2.3 Добавление сообщений в поток

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

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Мне нужно решить это уравнение `3x + 11 = 14`. Можете мне помочь?"
    }'

Параметры API:

thread_id - представляет идентификатор потока разговора, который можно получить при создании Потока.

Тело запроса API представляет собой сообщение пользователя, обычно представляющее вопрос пользователя, аналогичное структуре сообщения модели разговора.

2.4 Запуск помощника для генерации ответа

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

Примечание: До этого момента помощник не отвечал на вопрос пользователя. Только при вызове API Run помощник ИИ будет отвечать на вопрос пользователя.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "Обратитесь к пользователю как Джейн Доу. Пользователь - обладатель премиум-аккаунта."
  }'

Параметры API:

thread_id - представляет идентификатор потока разговора, который можно получить при создании Потока.
assistant_id - представляет идентификатор помощника, который можно получить при создании помощника.
instructions - инструкции помощника, которые могут переопределить инструкции, заданные при создании помощника.

Успешный запрос API вернет идентификатор Запуска.

2.5 Проверка состояния выполнения помощника

После запуска задачи (Запуск) в помощнике выполнение задачи является асинхронным. Это означает, что нам нужно регулярно проверять состояние Запуска, чтобы определить, завершен ли он. Для проверки состояния Запуска можно сделать HTTP-запрос с помощью CURL. Ниже приведено подробное описание этого процесса.

Пример запроса CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Пояснение параметров API:

https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Это URL запроса API, где thread_abc123 - уникальный идентификатор потока (Thread), а run_abc123 - уникальный идентификатор Запуска.

Пример тела ответа:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Пояснение параметров ответа API:

id: Уникальный идентификатор Запуска.
object: Указывает на тип возвращаемого объекта, который здесь является thread.run.
status: Статус Запуска, возможные значения: queued, in_progress, completed, requires_action, failed и т. д.
created_at: Временная метка создания Запуска.

2.6 Получение результатов ответа помощника

После завершения Запуска помощника мы можем прочитать результаты ответа помощника, проверив добавленные сообщения в поток (Thread). Ниже приведен пример того, как сделать запрос через CURL и подробное объяснение параметров API.

Подсказка: Подобно разговору с помощником, когда помощник завершает обработку запроса пользователя, помощник добавляет сообщение в поток разговора (Thread). Поэтому нам просто нужно запросить последнее сообщение в потоке разговора (Thread), чтобы получить ответ от помощника.

Пример запроса CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Объяснение параметров API:

https://api.openai.com/v1/threads/thread_abc123/messages: URL запроса к API, где thread_abc123 - уникальный идентификатор нити (Thread).
То же самое, что использовалось в заголовках запроса для проверки статуса выполнения ранее, включая информацию аутентификации и версию API.

Пример результата ответа помощника:

В этом примере пользователь задал помощнику математический вопрос, и помощник добавил ответное сообщение в нить после обработки.

Пользователь: Мне нужно решить уравнение `3x + 11 = 14`. Можете помочь?
Помощник: Конечно, Jane Doe. Чтобы решить уравнение `(3x + 11 = 14)`, нужно изолировать `(x)` на одной стороне уравнения. Позвольте мне вычислить значение `(x)` для вас.
Помощник: Решением уравнения `(3x + 11 = 14)` является `(x = 1)`.

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

3. Инструменты: Встроенные инструменты, предоставляемые OpenAI

3.1 Инструмент интерпретатора кода

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

Включение интерпретатора кода

Чтобы включить интерпретатор кода, передайте code_interpreter в параметре tools при создании объекта помощника:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Вы - личный математический репетитор. При запросе математического вопроса пишите и запускайте код для ответа.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Затем модель будет решать, когда вызывать интерпретатор кода во время выполнения, основываясь на характере запроса пользователя. Вы можете облегчить это поведение через instructions помощника (например, "Напишите код для решения этой проблемы").

Использование интерпретатора кода для обработки файлов

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

Файлы, переданные на уровне помощника, могут быть использованы всеми Запусками, связанными с этим помощником:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Вы - личный математический репетитор. При запросе математического вопроса пишите и запускайте код для ответа.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Чтение изображений и файлов, сгенерированных интерпретатором кода

Интерпретатор кода также может генерировать файлы в API, такие как создание графиков, файлы CSV и PDF файлы. Существуют два типа сгенерированных файлов: изображения и файлы данных (например, файл CSV с данными, сгенерированными помощником).

Когда интерпретатор кода создает изображение, вы можете найти и загрузить этот файл в поле file_id ответа сообщения помощника:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Инструмент извлечения

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

Включение извлечения

Для включения извлечения в параметре tools помощника, передайте retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Вы являетесь чат-ботом службы поддержки клиентов. Используйте вашу базу знаний для эффективного ответа на запросы клиентов.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Загрузка файлов для извлечения

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

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Вы являетесь чат-ботом службы поддержки клиентов. Используйте вашу базу знаний для эффективного ответа на запросы клиентов.",
    "name": "Репетитор по математике",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Инструмент вызова функций

Аналогично API завершения чата, API помощников поддерживает вызов функций. Вызов функций позволяет описывать функции помощнику и интеллектуально возвращать функцию для вызова вместе с ее параметрами. Когда вызов функции выполняется, API помощников приостановит выполнение, и вы можете предоставить результат вызова функции для продолжения выполнения.

Определение функций

При создании Ассистента вы можете определить набор функций, которые Ассистент будет вызывать. Эти функции должны быть явно указаны при создании объекта ассистента. Каждая функция должна иметь уникальное имя, описание и спецификацию параметров.

В следующем примере кода показано, как определить две функции с использованием команды curl при создании ассистента:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Вы являетесь ботом прогноза погоды. Используйте предоставленные функции для ответа на вопросы.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Получить погодные условия для конкретного местоположения",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Город и штат, например, Сан-Франциско, Калифорния"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Получить прозвище для города",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Город и штат, например, Сан-Франциско, Калифорния"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Чтение вызываемых функций Ассистентом

Когда пользователь отправляет сообщение Ассистенту, и содержимое сообщения вызывает вызов функции, вам необходимо прочитать информацию об этом вызове функции. В этот момент Ассистент будет генерировать объект запуска со статусом requires_action. На этом этапе вы можете извлечь объект Запуска, чтобы получить подробную информацию о вызове функции.

Вот пример извлечения объекта Запуска, показывающий, как получить информацию о вызовах функций:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

Параметр tool_calls содержит информацию о вызове функций, и вам просто нужно вызвать соответствующую функцию в вашей локальной программе.

Отправка результатов работы функций

После выполнения вызова функции локально и получения результатов, вам необходимо отправить эти результаты в ассистент Assistants, чтобы он мог продолжить обработку запроса пользователя. При отправке результатов функций вам необходимо убедиться, что результаты связаны с исходными вызовами функций.

Вот пример кода того, как отправить результаты работы функций:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Пояснение параметров:

thread_abc123 представляет идентификатор потока общения
run_123 представляет идентификатор объекта Запуска
tool_call_id представляет идентификатор конкретного вызова функции, который получается из предыдущего параметра tool_calls.

После успешной отправки всех результатов работы функций статус объекта Запуска будет снова обновлен, и ассистент продолжит обработку и вернет конечный ответ пользователю.

1. Представление API OpenAI Assistants

1.1 Определение и цель Assistants API

1.2 Применение API Assistants

1.3 Основные концепции Assistants

Assistant

Thread

Message

2.3 Добавление сообщений в поток

2.4 Запуск помощника для генерации ответа

2.5 Проверка состояния выполнения помощника

Пример запроса CURL:

Пояснение параметров API:

Пример тела ответа:

Пояснение параметров ответа API:

2.6 Получение результатов ответа помощника

Пример запроса CURL:

Объяснение параметров API:

Пример результата ответа помощника:

3. Инструменты: Встроенные инструменты, предоставляемые OpenAI

3.1 Инструмент интерпретатора кода

Включение интерпретатора кода

Использование интерпретатора кода для обработки файлов

Чтение изображений и файлов, сгенерированных интерпретатором кода

3.2 Инструмент извлечения

Включение извлечения

Загрузка файлов для извлечения

3.3 Инструмент вызова функций

Определение функций

Чтение вызываемых функций Ассистентом

Отправка результатов работы функций

Связанные Учебные Пособия