TNWS AI

Гайд · TNWS AI

Как настроить ModelSettings в OpenAI Agents SDK и проверить фактические параметры

WindowsmacOSLinuxChatGPT#нейросети#API#OpenAI Agents SDK
7 мин—

Настраиваем temperature, top_p, tool_choice, parallel_tool_calls, max_tokens и store; проверяем поддержку провайдером через ScriptedModel.

Задача и применимость

Этот гайд решает конкретную задачу: задать параметры модельного вызова централизованно и убедиться, что SDK передал именно ожидаемую конфигурацию. Он рассчитан на разработчика, который хочет получить воспроизводимый результат, а не просто увидеть удачный ответ один раз. Все названия классов, методов, параметров и полей ниже сверены с официальной документацией 12 сентября 2026 года. Цены и тарифы здесь не приводятся: для этой операции они не нужны, а стоимость модельных вызовов зависит от выбранной модели и аккаунта.

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

Подтверждённые единицы интерфейса

По официальному первоисточнику для этой задачи используются:

  • ModelSettings
  • temperature
  • top_p
  • tool_choice
  • parallel_tool_calls
  • max_tokens
  • verbosity
  • store
  • resolve()
  • не все провайдеры поддерживают все поля

Эти имена важно не «улучшать» по памяти. Похожее название из другого SDK может не существовать. Проверка документации выполнена 12 сентября 2026 года. Если после обновления пакета пример перестал работать, сначала сопоставьте установленную версию с текущей документацией и проверьте сигнатуру, а не отключайте обработку ошибок.

Что подготовить

  1. Изолированное окружение Python и файл без реальных ключей в исходном коде.
  2. Тестовый вход, для которого заранее известен ожидаемый итог.
  3. Отдельный негативный сценарий: отсутствующий объект, лишний шаг, неверное имя или недоступный сервис — в зависимости от операции.
  4. Журнал с временем, названием операции и итоговым статусом. Содержимое секретных заголовков в журнал не включайте.
  5. Для сетевого примера — явный таймаут. Бесконечное ожидание нельзя отличить от зависшего процесса.

Перед запуском зафиксируйте ожидаемый результат одной фразой. Это защищает от распространённой ошибки: считать любой валидный JSON или любой текст «успехом». Валидный ответ ещё должен удовлетворять бизнес-условию.

Пошаговая реализация

Шаг 1. Определите границу операции

Не объединяйте в одну функцию настройку клиента, бизнес-логику, печать и аварийное восстановление. Входные данные должны передаваться явно. Секреты читайте из переменных окружения. Для локального сервиса явно задайте адрес; для облачного SDK не подменяйте базовый URL без необходимости.

Шаг 2. Добавьте рабочий минимальный пример

Скопируйте заготовку и замените тестовые значения на свои:

from agents import Agent, RunConfig, Runner
+from agents.model_settings import ModelSettings
+from agents.testing import ScriptedModel, assistant_message
+
+model = ScriptedModel([[assistant_message("OK")]])
+settings = ModelSettings(
+    temperature=0.2,
+    tool_choice="auto",
+    parallel_tool_calls=False,
+    max_tokens=300,
+    store=False,
+)
+agent = Agent(name="Extractor", model=model, model_settings=settings)
+result = Runner.run_sync(agent, "Извлеки реквизиты", run_config=RunConfig(tracing_disabled=True))
+assert model.last_call.model_settings.temperature == 0.2
+assert model.last_call.model_settings.parallel_tool_calls is False
+model.assert_complete()

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

Шаг 3. Добавьте наблюдаемость

Записывайте начало операции, безопасный идентификатор запроса, HTTP-статус или тип события, длительность и итог. Для массивов полезно записывать количество элементов, а не всё содержимое. Для потоков храните последний корректный статус. Для агентного цикла отдельно считайте модельные шаги и tool calls: это разные величины.

Шаг 4. Проверьте негативный путь

Измените один параметр так, чтобы получить контролируемый отказ: укажите несуществующее имя, исчерпайте заданный бюджет или подготовьте лишний scripted step. Тест пройден, только если программа останавливается в ожидаемой ветке и сообщает точную причину. Общий except Exception: pass запрещён: он превращает отказ в ложный успех.

Реалистичный пример входа и ожидаемого результата

Вход. Задача извлечения реквизитов с параметрами temperature=0.2, parallel_tool_calls=False, max_tokens=300, store=False.

Ожидаемый результат. Детерминированный тест возвращает OK, а снимок model.last_call.model_settings содержит заданные значения. В бою неподдерживаемый параметр проверяется по документации конкретной модели и провайдера.

Сравнивайте не литературную формулировку, а проверяемые признаки: код статуса, тип исключения, значение обязательного поля, число вызовов или наличие объекта в повторном GET. Если ответ текстовый, отделите фактические утверждения от оформления и проверяйте факты отдельно.

Готовый шаблон задания для ревью

Этот промпт можно дать коллеге или модели для проверки кода. Он не заменяет выполнение тестов:

Проверь реализацию операции: [НАЗВАНИЕ].
Официальный контракт: [ССЫЛКА НА ДОКУМЕНТАЦИЮ].
Вход: [ТЕСТОВЫЕ ДАННЫЕ].
Ожидаемый результат: [ПРОВЕРЯЕМЫЕ ПОЛЯ/СТАТУС].

Найди только конкретные проблемы:

  1. неверные имена методов, параметров или полей;
  2. отсутствие таймаута и проверки статуса;
  3. утечку токена или пользовательских данных в лог;
  4. ложный успех при пустом или оборванном ответе;
  5. destructive-действие без preflight и подтверждения.

Для каждой проблемы укажи строку, риск и минимальное исправление. Не придумывай неподтверждённые лимиты и возможности.


## Проверка результата по уровням

Сначала проверьте транспорт: запрос завершился, статус допустим, JSON разобран. Затем контракт: обязательные поля имеют ожидаемые типы. После этого бизнес-условие: нужный объект найден, цикл ограничен, инструмент действительно выполнился или финальный статус получен. Последний уровень — повторная проверка независимым чтением состояния, если операция его меняет.

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

## Типичные ошибки

- не выставляйте одновременно temperature и top_p без понятной причины
- не предполагайте, что любой провайдер поддерживает каждое поле ModelSettings
- различайте `parallel_tool_calls` — право модели выдать несколько вызовов — и лимит параллельного исполнения на стороне SDK

Ещё одна ошибка — копировать пример целиком в production без лимитов времени и размера. Документационный пример показывает контракт, но эксплуатационный код должен учитывать повтор, отмену, идемпотентность и наблюдаемость. Повторяйте только операции, для которых понимаете последствия; DELETE и другие destructive-вызовы автоматически не повторяйте.

## Чек-лист финальной проверки

- [ ] Названия методов, классов, параметров и полей сверены с официальным источником 12 сентября 2026 года.
- [ ] Секреты находятся в переменных окружения и не попадают в лог.
- [ ] Для сетевого вызова задан таймаут; для цикла — явная граница или контролируемое завершение.
- [ ] Проверяется не только отсутствие исключения, но и обязательный итоговый признак.
- [ ] Пустой ответ, неизвестное имя или лишний шаг обработаны как отдельный негативный тест.
- [ ] После изменяющей операции выполнено независимое чтение состояния.
- [ ] Лог содержит безопасный идентификатор, статус и длительность, но не персональные данные.
- [ ] Тестовый пример не использует производственные объекты.

## Ограничения

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

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

## FAQ

### Достаточно ли получить HTTP 200 или финальный текст?

Нет. HTTP 200 подтверждает транспортный уровень, а текст — только наличие вывода. Нужна проверка обязательного поля, статуса, количества вызовов или повторное чтение состояния. Именно этот признак должен быть зафиксирован в тесте.

### Можно ли автоматически повторять запрос после любой ошибки?

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

### Что записывать в журнал?

Время, безопасный ID операции, имя метода, длительность, тип результата и код ошибки. Не записывайте токены, заголовок Authorization, полный промпт, персональные данные и большие ответы. Для диагностики обычно достаточно числа элементов и названий ключей.

### Как понять, что пример не устарел?

Сверьте текущую документацию, установленную версию пакета или сервиса и выполните оба сценария: ожидаемый успех и контролируемую ошибку. Дата проверки этого материала — 12 сентября 2026 года; она не отменяет повторную сверку после обновления.

## Официальные первоисточники

- [Документация для описанной операции](https://openai.github.io/openai-agents-python/ref/model_settings/)

Материал написан самостоятельно по контракту официальной документации; примеры результатов выше являются ожидаемыми условиями теста, а не заявлением о стороннем benchmark.

Читайте также

ГайдыWindowsmacOS12 сентября 2026

Как проверять агента в терминале через REPL OpenAI Agents SDK

Запускаем run_demo_loop, проверяем многошаговый контекст и streaming, составляем сценарий ручной приёмки и отделяем REPL от автоматических тестов.

7 мин 
ГайдыWindowsmacOS12 сентября 2026

Как настроить lifecycle hooks в OpenAI Agents SDK для аудита вызовов

Подключаем RunHooks и AgentHooks, считаем вызовы модели и инструментов, не записываем секреты и проверяем порядок событий агентного запуска.

7 мин 
ГайдыWindowsmacOS12 сентября 2026

Как ограничить число шагов агента через max_turns в OpenAI Agents SDK

Практический гайд по max_turns и MaxTurnsExceeded: ограничиваем агентный цикл, сохраняем диагностику и проверяем сценарий с повторными tool calls.

7 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово