Роли API OpenAI и входные данные

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

Зачем нужны роли

Если отправить модели всё одной строкой, например «Отвечай кратко. Меня зовут Дима. Приятно познакомиться. Как меня зовут?», ей придётся самой разбираться, что здесь инструкция, что сказал человек и чего от неё хотят. Роли снимают эту неоднозначность: каждый кусок текста помечен тем, кто его написал.

Второе применение ролей - память. Модель не помнит прошлые запросы, поэтому в чате перед каждым новым вопросом ей заново передают историю переписки: что писал человек, какие были системные инструкции и что отвечала сама модель. Так она знает, что пользователь уже представился, и может назвать его по имени.

Три роли

• developer (или system, это одно и то же) - системные инструкции: как модель должна себя вести, каких правил придерживаться.
• user - то, что пишет человек.
• assistant - то, что ответила модель.

Пример запроса с историей переписки

Входные данные передаются в аргументе input метода client.responses.create. Это список сообщений, у каждого есть роль и содержимое. Как подключить библиотеку и создать клиента, разобрано в уроке О библиотеке openai для Python.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5-mini",
    input=[
        {"role": "developer", "content": "Отвечай кратко"},
        {"role": "user", "content": "Меня зовут Дима"},
        {"role": "assistant", "content": "Приятно познакомиться, Дима!"},
        {"role": "user", "content": "Как меня зовут?"},
    ],
)
print(response.output_text)

Здесь модель получает системную инструкцию отвечать кратко, затем видит, что пользователь представился Димой, а ассистент с ним поздоровался. На последний вопрос «Как меня зовут?» она ответит с учётом всей этой истории.

Содержимое сообщения может быть списком

Поле content не обязательно строка. В него можно передать список элементов разного типа: текст, картинку, файл.

response = client.responses.create(
    model="gpt-5-mini",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Что не дорисовано на рисунке?"},
            {"type": "input_image", "image_url": f"data:image/png;base64,{image_b64}"},
        ],
    }],
)

• input_text - обычный текст;
• input_image - картинка, закодированная в Base64 (или ссылка на неё);
• input_file - файл, тоже в Base64:

{"type": "input_file", "filename": "report.pdf", "file_data": f"data:application/pdf;base64,{pdf_b64}"}

Где писать системные инструкции

Системные инструкции можно задать тремя способами, и все они рабочие:

1. сообщением с ролью system;
2. сообщением с ролью developer;
3. отдельным аргументом instructions:

response = client.responses.create(
    model="gpt-5-mini",
    instructions="Отвечай кратко",
    input="Как меня зовут?",
)

В API OpenAI вообще часто есть несколько вариантов записать одно и то же, и библиотека принимает их все. Встретив в чужом коде другую форму, не стоит считать её ошибкой.

Итог

Есть три роли: developer (system), user и assistant. С их помощью модели передают нужный контекст: правила поведения, предыдущую переписку и вводные данные, которые она учтёт при ответе. А содержимое сообщения может быть не только текстом, но и списком из текста, картинок и файлов.