Справочник по конфигурации dbt Wizard Бета-версия
dbt Wizard хранит конфигурацию в двух файлах TOML в каталоге ~/.dbt/wizard/, каждый из которых управляет отдельной частью продукта.
Два файла конфигурации
Хотите увидеть dbt Wizard в действии? Посмотрите демонстрационное видео.
Нам было бы интересно узнать о вашем опыте работы с dbt Wizard. Поделитесь отзывом, выполнив слеш-команду /feedback в интерактивном сеансе терминала или перейдя в канал #dbt-wizard в Slack-сообществе dbt.
Большое спасибо за помощь в улучшении dbt Wizard и процесса разработки данных с помощью dbt!
TOML (Tom's Obvious, Minimal Language) — это формат файлов конфигурации. Если вы уже работали с YAML или JSON, он покажется вам знакомым — ключи и значения разделяются знаком = (с пробелами до и после знака равенства), а для вложенных разделов используются заголовки [section.name] вместо отступов или фигурных скобок. Например:
model = "gpt-4o"
[projects."/Users/you/jaffle-shop"]
trust_level = "trusted"
Эта конфигурация задаёт модель ИИ по умолчанию для всех новых сеансов и применяется ко всем последующим запускам во всех проектах. Вы можете переопределить модель ИИ по умолчанию для конкретного проекта, задав ключ model в файле wizard_config.toml для этого проекта или воспользовавшись меню выбора /model в текстовом пользовательском интерфейсе (TUI).
| Файл | Чем управляет | Когда использовать |
|---|---|---|
~/.dbt/wizard/config.toml | Среда выполнения агента — модель ИИ, серверы MCP, правила подтверждения, доверенные проекты | Чтобы изменить поведение агента во всех сеансах |
~/.dbt/wizard/wizard_config.toml | Настройки отдельных проектов — путь к исполняемому файлу dbt, отложенное разрешение ссылок, сохранённые предпочтения модели | Чтобы изменить работу dbt Wizard с конкретным проектом dbt |
Обратите внимание: dbt_project.yml — это отдельный файл, который управляет тем, как dbt собирает ваш проект.
Типовые задачи
| Цель | Что изменить | Нужен перезапуск? |
|---|---|---|
| Изменить модель ИИ по умолчанию | config.toml → model = "gpt-4o" | Да |
| Указать dbt Wizard конкретный исполняемый файл dbt | wizard_config.toml → path | Да |
| Добавить сервер dbt MCP | config.toml → [mcp_servers.dbt] | Да |
| Пометить репозиторий как доверенный | config.toml → trust_level = "trusted" в разделе [projects."..."] | Да |
| Изменить настройки подтверждения или песочницы по умолчанию | config.toml | Да |
Приоритет настроек
Настройки применяются в следующем порядке (от наивысшего приоритета к низшему):
- Флаги CLI (
-m,-c), указанные при запуске - Меню выбора модели в сеансе (
/model) ~/.dbt/wizard/config.toml~/.dbt/wizard/wizard_config.toml- Встроенные значения по умолчанию
config.toml
Глобальные настройки агента: модели, подтверждения, песочница, веб-поиск и серверы MCP.
~/.dbt/wizard/config.toml управляет поведением сеанса агента. Он создаётся автоматически при установке dbt Wizard.
Ключи конфигурации
Ниже перечислены ключи конфигурации, которые можно задать в config.toml.
modelapproval_policysandbox_modeweb_search
Чтобы узнать больше, выполните wizard config --help.
Модель ИИ и API
При новой установке CLI dbt Wizard по умолчанию используются модели, управляемые dbt Labs. Чтобы использовать другого поставщика, см. раздел Настройка BYOK.
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
model | string | — | Модель ИИ по умолчанию для новых сеансов. См. раздел Формат идентификатора модели ИИ ниже. Для интерактивного изменения используйте /model в TUI. |
Поведение
| Ключ | Тип | По умолчанию | Описание |
|---|---|---|---|
approval_policy | string | on-request | Определяет, когда Wizard запрашивает подтверждение перед выполнением команд. Варианты: untrusted (запрашивать для недоверенных команд), on-request (решает dbt Wizard), never (выполнять без запроса). |
sandbox_mode | string | read-only | Политика песочницы для командной оболочки. Варианты: read-only (по умолчанию), workspace-write (разрешить запись в каталоге проекта), danger-full-access (без ограничений). |
web_search | string | cached | Режим веб-поиска. Варианты: disabled, cached или live. |
Доверие к проекту
Задайте trust_level для отдельного проекта, чтобы разрешить dbt Wizard использовать локальную конфигурацию проекта:
[projects."/absolute/path/to/your-repo"]
trust_level = "trusted"
Серверы MCP
[mcp_servers.dbt]
command = "DBT_MCP_ENDPOINT"
Формат идентификатора модели ИИ
В качестве идентификаторов моделей ИИ в config.toml используются публичные идентификаторы моделей, например gpt-4o.
Чтобы вывести список всех доступных идентификаторов моделей ИИ:
wizard debug models
Переменные окружения
Любой ключ можно задать через переменную окружения с префиксом DBT_WIZARD_, записав имя в формате SCREAMING_SNAKE_CASE:
export DBT_WIZARD_MODEL=gpt-4o
export DBT_WIZARD_APPROVAL_POLICY=never
export OPENAI_API_KEY=sk-... # OpenAI (префикс не нужен)
export ANTHROPIC_API_KEY=sk-ant-... # Anthropic (префикс не нужен)
OPENAI_API_KEY и ANTHROPIC_API_KEY считываются напрямую без префикса DBT_WIZARD_, в соответствии с соглашениями каждого поставщика.
Когда считывается файл
config.toml считывается в начале сеанса при запуске wizard. Изменения вступают в силу только после выхода из CLI и его перезапуска. Флаги -c, указанные для отдельного запуска, и меню выбора /model внутри сеанса переопределяют настройки этого файла только для текущего сеанса.
Пример
model = "gpt-4o"
[projects."/Users/you/jaffle-shop"]
trust_level = "trusted"
[mcp_servers.dbt]
command = "DBT_MCP_ENDPOINT"
wizard_config.toml
Настройки отдельных проектов, которые Wizard записывает во время первоначальной настройки, включая путь к dbt и параметры отложенного разрешения ссылок.
~/.dbt/wizard/wizard_config.toml хранит сведения dbt Wizard о каждом из ваших проектов dbt. dbt Wizard автоматически записывает данные в этот файл во время первоначальной настройки и при изменении настроек проекта. Вы также можете редактировать его вручную.
Ключи конфигурации
| Ключ | Описание |
|---|---|
version | Версия схемы этого файла (сейчас 1). Не изменяйте её вручную. |
global.terms_of_use_accepted_at | Отметка времени принятия Условий использования dbt Wizard. Записывается один раз в разделе [global] и применяется ко всем проектам. |
global.dbt_compile_on_startup | Определяет, нужно ли компилировать проект разработки при запуске. По умолчанию true. |
global.prod_parse_on_startup | Определяет, нужно ли выполнять разбор производственной среды и обновлять состояние для отложенного разрешения ссылок при запуске. По умолчанию true. |
global.prod_parse_args | Аргументы для разбора производственной среды. По умолчанию ["parse", "--target", "prod"]. |
global.prod_state_ttl_hours | Количество часов, в течение которых снимок состояния производственной среды считается актуальным. По умолчанию 24. |
global.prod_state_dir | Каталог для снимков состояния производственной среды. По умолчанию target/prod-state в проекте. |
global.compile_extra_args | Дополнительные аргументы, добавляемые при компиляции любого проекта в dbt Wizard, если для проекта не задано переопределение. |
onboarded_at | Отметка времени первоначальной настройки этого проекта в dbt Wizard. |
path | Путь к исполняемому файлу dbt, который dbt Wizard должен использовать для этого проекта. |
compile_extra_args | Дополнительные аргументы, добавляемые при компиляции этого проекта в dbt Wizard. |
prod_parse_args | Аргументы команды разбора производственной среды для конкретного проекта. |
deferral.mode | Определяет, кто управляет отложенным разрешением ссылок для этого проекта. См. раздел Отложенное разрешение ссылок ниже. |
deferral.target | Целевая среда (target) из вашего profiles.yml, которую dbt Wizard компилирует и использует для отложенного разрешения ссылок, когда deferral.mode имеет значение "wizard" (например, "prod"). |
deferral.state | Путь к каталогу состояния, когда deferral.mode имеет значение "manual". |
deferral.favor_state | Определяет, имеют ли приоритет отношения, используемые при отложенном разрешении ссылок. По умолчанию true. |
profile_override.path | Путь к альтернативному файлу profiles.yml для этого проекта. |
profile_override.profile | Имя профиля из выбранного файла профилей, который следует использовать. |
profile_override.target | Целевая среда из выбранного профиля, которую следует использовать. |
Настройки хранятся отдельно для каждого проекта в блоках [projects."/absolute/path/to/repo"]:
version = 1
[global]
terms_of_use_accepted_at = "2026-05-28T15:06:54Z"
dbt_compile_on_startup = true
prod_parse_on_startup = true
prod_state_ttl_hours = 24
[projects."/Users/you/jaffle-shop"]
onboarded_at = "2026-05-20T11:09:01.410346"
path = "/Users/you/jaffle-shop/.venv/bin/dbt"
[projects."/Users/you/jaffle-shop".deferral]
mode = "wizard"
target = "prod"
favor_state = true
Отложенное разрешение ссылок
Отложенное разрешение ссылок (deferral) позволяет dbt Wizard повторно использовать модели, уже собранные в другой среде (например, в производственной), вместо того чтобы пересобирать всё, когда вы работаете только с частью проекта. Это экономит время и снижает затраты на хранилище данных.
Настройка deferral.mode в wizard_config.toml определяет, кто управляет отложенным разрешением ссылок. Она принимает шесть значений, и dbt Wizard обычно задаёт её за вас во время первоначальной настройки:
Значение deferral.mode | Что оно означает |
|---|---|
"wizard" | dbt Wizard управляет отложенным разрешением ссылок за вас. Вы указываете dbt Wizard, какую целевую среду из вашего profiles.yml использовать для отложенного разрешения ссылок (при первоначальной настройке проекта он пытается определить её автоматически). Затем dbt Wizard компилирует эту целевую среду и повторно использует её модели для любых вышестоящих моделей, которые вы ещё не собрали самостоятельно. |
"fusion_cloud" | dbt platform управляет отложенным разрешением ссылок на основе подключённой среды, поэтому dbt Wizard не управляет локальным состоянием. Задаётся автоматически при подключении к платформе. |
"cloud_cli" | dbt platform CLI управляет учётными данными и отложенным разрешением ссылок через dbt platform, поэтому dbt Wizard пропускает компиляцию производственной среды и добавление флагов отложенного разрешения ссылок. |
"dbt_state" | dbt State или кеш запусков управляет отложенным разрешением ссылок, поэтому dbt Wizard пропускает собственную компиляцию производственной среды. |
"manual" | Вы указываете каталог с манифестом для отложенного разрешения ссылок с помощью state. |
"disabled" | Отложенное разрешение ссылок отключено для проекта. |
Подробнее о dbt State см. в разделе О dbt State.
Если mode = "manual", задайте для state каталог, содержащий совместимый файл manifest.json:
[projects."/Users/you/jaffle-shop".deferral]
mode = "manual"
state = "/Users/you/dbt-state/production"
favor_state = true
О параметре favor-state: параметр favor_state настраивается и по умолчанию имеет значение true. При значении true dbt Wizard передаёт --favor-state, чтобы отношения, используемые при отложенном разрешении ссылок, имели приоритет. Задайте false, чтобы использовать отношение, уже существующее в среде разработки, и обращаться к состоянию для отложенного разрешения ссылок, только если такого отношения нет.
Вы также можете настроить поведение снимков производственной среды и компиляции с помощью глобальных параметров prod_parse_on_startup, prod_parse_args, prod_state_ttl_hours, prod_state_dir и compile_extra_args. Значения compile_extra_args и prod_parse_args на уровне проекта позволяют переопределить глобальное поведение для одного проекта. Используйте блок profile_override, чтобы выбрать другой файл профилей, профиль или целевую среду для компиляции.
Примеры конфигурации и порядок проверки см. в разделе Разработка с отложенным разрешением ссылок на производственную среду.
Устранение неполадок
Ниже приведены распространённые ошибки конфигурации и способы их устранения:
| Симптом | Вероятная причина | Решение |
|---|---|---|
После редактирования wizard_config.toml по-прежнему используется прежняя модель ИИ | wizard_config.toml не хранит модель | Задайте model в config.toml и перезапустите wizard |
Модель ИИ не изменилась после редактирования config.toml | Старый сеанс всё ещё работает | Нажмите Ctrl+C, затем снова запустите wizard |
| Ошибка "Invalid model" | Неверный идентификатор модели ИИ | Выполните wizard debug models, чтобы увидеть допустимые идентификаторы моделей ИИ |
Повторный запуск процедур первоначальной настройки
Если вам нужно повторить часть настройки — например, после случайного удаления записей конфигурации или перехода к новому проекту, — вы можете сбросить отдельные процедуры, удалив соответствующий файл. При следующем запуске dbt Wizard снова предложит выполнить настройку.
Чтобы удалить файл, выполните команду в терминале (macOS/Linux). Например:
rm ~/.dbt/wizard/auth.json
Если вы получили ошибку No such file or directory, файл не существует — это означает, что соответствующая часть настройки ещё не выполнялась или уже была сброшена. Эту ошибку можно игнорировать.
| Что вы хотите повторить | Какой файл удалить |
|---|---|
| Повторно вызвать запрос о доверии к папке | Удалите запись вашего проекта из ~/.dbt/wizard/config.toml в разделе [projects."..."] |
| Повторно пройти аутентификацию в dbt platform | ~/.dbt/wizard/auth.json |
| Повторно настроить проект dbt | Удалите запись вашего проекта из ~/.dbt/wizard/wizard_config.toml в разделе [projects."..."] или удалите файл целиком, чтобы сбросить все проекты |
| Повторно запустить настройку ключа BYOK | ~/.dbt/wizard/provider* (соответствует всем файлам поставщиков) |
config.toml и wizard_config.toml — это отдельные файлы, которые управляют разными настройками. Если вы хотите повторно настроить проект, изменяйте wizard_config.toml, а не config.toml. Изменение не того файла не запустит ожидаемую процедуру первоначальной настройки. Различия описаны в разделе Два файла конфигурации в начале этой страницы.
Связанная документация
Ссылки на настройку BYOK, порядок подтверждения действий и справочник команд CLI.
- Настройка BYOK
- Подтверждение действий и песочница
- Справочник команд dbt Wizard
- Как работает dbt Wizard
