Model Providers

Qwen Code позволяет настраивать несколько провайдеров моделей через параметр modelProviders в файле settings.json. Это даёт возможность переключаться между разными AI-моделями и провайдерами с помощью команды /model.

Обзор

Используйте modelProviders, чтобы объявить модели для каждого типа аутентификации, между которыми можно переключаться через инструмент выбора /model. Ключи должны быть допустимыми типами аутентификации (openai, anthropic, gemini и т.д.). Каждый тип аутентификации сопоставляется с объектом ProviderConfig, содержащим поле protocol и поле models (массив определений моделей). Каждая запись в models требует id; envKey является необязательным и рекомендуемым (если опущен, используется ключ по умолчанию для данного типа аутентификации, например OPENAI_API_KEY для openai), также доступны опциональные поля name, description, baseUrl и generationConfig. Учётные данные никогда не сохраняются в настройках; среда выполнения считывает их из process.env[envKey]. Модели Qwen OAuth остаются жёстко заданными и не могут быть переопределены.

Примеры конфигурации по типам аутентификации

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

Поддерживаемые типы аутентификации

Ключи объекта modelProviders должны быть допустимыми значениями authType. В настоящее время поддерживаются следующие типы аутентификации:

[!warning] Если используется неизвестный ключ типа аутентификации (например, опечатка "openai-custom"), непустой ключ принимается как есть как отдельная группа типа аутентификации, но не сопоставляется с известным протоколом — поэтому его модели не будут работать должным образом и не будут корректно отображаться в инструменте выбора /model. Пропускаются только пустые ключи (содержащие только пробелы или пустые строки). Всегда используйте одно из поддерживаемых значений типа аутентификации, перечисленных выше.

SDK, используемые для API-запросов

Qwen Code использует следующие официальные SDK для отправки запросов к каждому провайдеру:

Это означает, что настраиваемый baseUrl должен быть совместим с ожидаемым форматом API соответствующего SDK. Например, при использовании типа аутентификации openai эндпоинт должен принимать запросы в формате API OpenAI.

Провайдеры, совместимые с OpenAI (openai)

Этот тип аутентификации поддерживает не только официальный API OpenAI, но и любые эндпоинты, совместимые с OpenAI, включая агрегированных провайдеров моделей, таких как OpenRouter и Requesty.

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here",
    "REQUESTY_API_KEY": "sk-your-actual-requesty-key-here"
  },
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "envKey": "OPENAI_API_KEY",
          "baseUrl": "https://api.openai.com/v1",
          "generationConfig": {
            "timeout": 60000,
            "maxRetries": 3,
            "enableCacheControl": true,
            "contextWindowSize": 128000,
            "modalities": {
              "image": true
            },
            "customHeaders": {
              "X-Client-Request-ID": "req-123"
            },
            "extra_body": {
              "enable_thinking": true,
              "service_tier": "priority"
            },
            "samplingParams": {
              "temperature": 0.2,
              "top_p": 0.8,
              "max_tokens": 4096,
              "presence_penalty": 0.1,
              "frequency_penalty": 0.1
            }
          }
        },
        {
          "id": "gpt-4o-mini",
          "name": "GPT-4o Mini",
          "envKey": "OPENAI_API_KEY",
          "baseUrl": "https://api.openai.com/v1",
          "generationConfig": {
            "timeout": 30000,
            "samplingParams": {
              "temperature": 0.5,
              "max_tokens": 2048
            }
          }
        },
        {
          "id": "openai/gpt-4o",
          "name": "GPT-4o (via OpenRouter)",
          "envKey": "OPENROUTER_API_KEY",
          "baseUrl": "https://openrouter.ai/api/v1",
          "generationConfig": {
            "timeout": 120000,
            "maxRetries": 3,
            "samplingParams": {
              "temperature": 0.7
            }
          }
        },
        {
          "id": "openai/gpt-4o-mini",
          "name": "GPT-4o Mini (via Requesty)",
          "envKey": "REQUESTY_API_KEY",
          "baseUrl": "https://router.requesty.ai/v1",
          "generationConfig": {
            "timeout": 120000,
            "maxRetries": 3,
            "samplingParams": {
              "temperature": 0.7
            }
          }
        }
      ]
    }
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": {
      "protocol": "anthropic",
      "models": [
        {
          "id": "claude-3-5-sonnet",
          "name": "Claude 3.5 Sonnet",
          "envKey": "ANTHROPIC_API_KEY",
          "baseUrl": "https://api.anthropic.com/v1",
          "generationConfig": {
            "timeout": 120000,
            "maxRetries": 3,
            "contextWindowSize": 200000,
            "samplingParams": {
              "temperature": 0.7,
              "max_tokens": 8192,
              "top_p": 0.9
            }
          }
        },
        {
          "id": "claude-3-opus",
          "name": "Claude 3 Opus",
          "envKey": "ANTHROPIC_API_KEY",
          "baseUrl": "https://api.anthropic.com/v1",
          "generationConfig": {
            "timeout": 180000,
            "samplingParams": {
              "temperature": 0.3,
              "max_tokens": 4096
            }
          }
        }
      ]
    }
  }
}

Google Gemini (gemini)

{
  "env": {
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "modelProviders": {
    "gemini": {
      "protocol": "gemini",
      "models": [
        {
          "id": "gemini-2.0-flash",
          "name": "Gemini 2.0 Flash",
          "envKey": "GEMINI_API_KEY",
          "baseUrl": "https://generativelanguage.googleapis.com",
          "capabilities": {
            "vision": true
          },
          "generationConfig": {
            "timeout": 60000,
            "maxRetries": 2,
            "contextWindowSize": 1000000,
            "schemaCompliance": "auto",
            "samplingParams": {
              "temperature": 0.4,
              "top_p": 0.95,
              "max_tokens": 8192,
              "top_k": 40
            }
          }
        }
      ]
    }
  }
}

Локальные самостоятельно размещённые модели (через API, совместимый с OpenAI)

Большинство локальных серверов вывода (vLLM, Ollama, LM Studio и т.д.) предоставляют эндпоинт API, совместимый с OpenAI. Настройте их, используя тип аутентификации openai с локальным baseUrl:

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "qwen2.5-7b",
          "name": "Qwen2.5 7B (Ollama)",
          "envKey": "OLLAMA_API_KEY",
          "baseUrl": "http://localhost:11434/v1",
          "generationConfig": {
            "timeout": 300000,
            "maxRetries": 1,
            "contextWindowSize": 32768,
            "samplingParams": {
              "temperature": 0.7,
              "top_p": 0.9,
              "max_tokens": 4096
            }
          }
        },
        {
          "id": "llama-3.1-8b",
          "name": "Llama 3.1 8B (vLLM)",
          "envKey": "VLLM_API_KEY",
          "baseUrl": "http://localhost:8000/v1",
          "generationConfig": {
            "timeout": 120000,
            "maxRetries": 2,
            "contextWindowSize": 128000,
            "samplingParams": {
              "temperature": 0.6,
              "max_tokens": 8192
            }
          }
        },
        {
          "id": "local-model",
          "name": "Local Model (LM Studio)",
          "envKey": "LMSTUDIO_API_KEY",
          "baseUrl": "http://localhost:1234/v1",
          "generationConfig": {
            "timeout": 60000,
            "samplingParams": {
              "temperature": 0.5
            }
          }
        }
      ]
    }
  }
}

Для локальных серверов, не требующих аутентификации, можно использовать любое значение-заполнитель для API-ключа:

# Для Ollama (аутентификация не требуется)
export OLLAMA_API_KEY="ollama"
 
# Для vLLM (если аутентификация не настроена)
export VLLM_API_KEY="not-needed"

Alibaba Cloud Coding Plan

Alibaba Cloud Coding Plan предоставляет предварительно настроенный набор моделей Qwen, оптимизированных для задач кодирования. Эта функция доступна пользователям с доступом к API Alibaba Cloud Coding Plan и предлагает упрощённую настройку с автоматическим обновлением конфигурации моделей.

Обзор

Когда вы проходите аутентификацию с помощью API-ключа Alibaba Cloud Coding Plan через команду /auth, Qwen Code автоматически настраивает следующие модели:

Настройка

1. Получите API-ключ Alibaba Cloud Coding Plan:
   • Китай: https://bailian.console.aliyun.com/?tab=model#/efm/coding_plan 
   • Международный: https://modelstudio.console.alibabacloud.com/?tab=dashboard#/efm/coding_plan 
2. Выполните команду /auth в Qwen Code
3. Выберите Alibaba ModelStudio, затем выберите Coding Plan из подменю
4. Выберите ваш регион
5. Введите ваш API-ключ по запросу

Модели будут автоматически настроены и добавлены в инструмент выбора /model.

Регионы

Alibaba Cloud Coding Plan поддерживает два региона:

Регион выбирается во время аутентификации и сохраняется в settings.json в конфигурации modelProviders. Чтобы сменить регион, повторно выполните команду /auth и выберите другой регион.

Хранение API-ключа

При настройке Coding Plan через команду /auth API-ключ сохраняется с использованием зарезервированного имени переменной окружения BAILIAN_CODING_PLAN_API_KEY. По умолчанию он хранится в поле env вашего файла settings.json.

# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=your-api-key-here

Автоматические обновления

Конфигурации моделей Coding Plan имеют версии. Когда Qwen Code обнаруживает более новую версию шаблона модели, вам будет предложено обновить её. Принятие обновления приведёт к:

• Замене существующих конфигураций моделей Coding Plan на последние версии
• Сохранению любых пользовательских конфигураций моделей, добавленных вручную
• Автоматическому переключению на первую модель в обновлённой конфигурации

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

Ручная конфигурация (продвинутая)

Если вы предпочитаете настроить модели Coding Plan вручную, вы можете добавить их в свой settings.json как любого другого провайдера, совместимого с OpenAI:

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "qwen3-coder-plus",
          "name": "qwen3-coder-plus",
          "description": "Qwen3-Coder через Alibaba Cloud Coding Plan",
          "envKey": "YOUR_CUSTOM_ENV_KEY",
          "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
        }
      ]
    }
  }
}

Уровни разрешения и атомарность

Результирующие значения auth/model/credential выбираются для каждого поля по следующему приоритету (первый найденный выигрывает). Вы можете комбинировать --auth-type с --model, чтобы напрямую указать на запись провайдера; эти флаги CLI выполняются перед остальными уровнями.

Наслоение конфигурации генерации: непроницаемый слой провайдера

Разрешение конфигурации следует строгой модели наслоения с одним ключевым правилом: слой modelProvider непроницаем.

Как это работает

1. Когда выбрана модель из modelProvider (например, через команду /model с выбором модели, настроенной у провайдера):

   • Весь generationConfig от провайдера применяется атомарно
   • Слой провайдера полностью непроницаем — нижние слои (CLI, env, settings) вообще не участвуют в разрешении generationConfig
   • Все поля, определенные в modelProviders[].generationConfig, используют значения провайдера
   • Все поля, не определенные провайдером, устанавливаются в undefined (не наследуются из настроек)
   • Это гарантирует, что конфигурации провайдера действуют как полный самодостаточный “запечатанный пакет”

   Если модель перечислена в modelProviders, поместите все настройки генерации, специфичные для этой модели, в соответствующую запись провайдера. Значения model.generationConfig верхнего уровня, включая contextWindowSize, modalities, customHeaders и extra_body, игнорируются для моделей провайдера. Чтобы они применялись, настройте эти поля в modelProviders[authType][].generationConfig.

2. Когда ни одна модель из modelProvider не выбрана (например, при использовании --model с raw ID модели, или при прямом использовании CLI/env/settings):

   • Разрешение опускается на нижние слои
   • Поля заполняются из CLI → env → settings → defaults
   • Это создает Runtime Model (см. следующий раздел)

Приоритет полей для generationConfig

Обработка атомарных полей

Следующие поля обрабатываются как атомарные объекты — значения провайдера полностью заменяют весь объект, слияния не происходит:

• samplingParams — Temperature, top_p, max_tokens и т.д.
• customHeaders — Пользовательские HTTP-заголовки
• extra_body — Дополнительные параметры тела запроса

Пример

// Файл настроек пользователя (~/.qwen/settings.json)
{
  "model": {
    "generationConfig": {
      "timeout": 30000,
      "samplingParams": { "temperature": 0.5, "max_tokens": 1000 }
    }
  }
}
 
// Конфигурация modelProviders
{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [{
        "id": "gpt-4o",
        "envKey": "OPENAI_API_KEY",
        "generationConfig": {
          "timeout": 60000,
          "samplingParams": { "temperature": 0.2 }
        }
      }]
    }
  }
}

Когда выбран gpt-4o из modelProviders:

• timeout = 60000 (от провайдера, переопределяет настройки)
• samplingParams.temperature = 0.2 (от провайдера, полностью заменяет объект из настроек)
• samplingParams.max_tokens = undefined (не определено у провайдера, и слой провайдера не наследует из настроек — поля явно устанавливаются в undefined, если не предоставлены)

При использовании raw модели через --model gpt-4 (не из modelProviders, создает Runtime Model):

• timeout = 30000 (из настроек)
• samplingParams.temperature = 0.5 (из настроек)
• samplingParams.max_tokens = 1000 (из настроек)

Стратегия слияния для самого modelProviders — REPLACE: весь modelProviders из настроек проекта переопределяет соответствующий раздел в пользовательских настройках, а не сливается с ним.

Конфигурация рассуждения / мышления

Необязательное поле reasoning в generationConfig управляет тем, насколько интенсивно модель рассуждает перед ответом. Конвертеры Anthropic и Gemini всегда соблюдают его. Конвейер, совместимый с OpenAI, соблюдает его если не задан generationConfig.samplingParams — см. примечание “Взаимодействие с samplingParams” ниже.

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "baseUrl": "https://api.deepseek.com/v1",
          "envKey": "DEEPSEEK_API_KEY",
          "generationConfig": {
            // Четырехуровневая шкала:
            //   'low'    | 'medium' — на сервере преобразуется в 'high' для DeepSeek
            //   'high'   — интенсивность рассуждения по умолчанию
            //   'max'    — дополнительный сильный уровень, специфичный для DeepSeek
            // Или установите `false`, чтобы полностью отключить рассуждение.
            "reasoning": { "effort": "max" },
          },
        },
      ],
    },
  },
}

Поведение по провайдерам

reasoning: false

Установка reasoning: false (буквальное логическое значение) явно отключает мышление у всех провайдеров — полезно для дешевых побочных запросов, которым не нужно рассуждение. Это также соблюдается на уровне запроса через request.config.thinkingConfig.includeThoughts: false для разовых вызовов (например, генерация предложений).

На baseURL api.deepseek.com конвейер OpenAI передает явное поле thinking: { type: 'disabled' }, необходимое для DeepSeek V4+ — серверное значение по умолчанию — 'enabled', поэтому простое опускание reasoning_effort все равно будет оплачивать задержку/стоимость рассуждения. Самостоятельно размещенные бэкенды DeepSeek (sglang/vllm) и другие серверы, совместимые с OpenAI, не получают это поле; если нужно отключить мышление на них, добавьте thinking: { type: 'disabled' } (или другой параметр, предоставляемый вашим фреймворком инференса) через samplingParams/extra_body.

Взаимодействие с samplingParams (только OpenAI-совместимые)

budget_tokens

Вы можете задать точный бюджет токенов на мышление, включив budget_tokens вместе с effort:

"reasoning": { "effort": "high", "budget_tokens": 50000 }

Для Anthropic это превращается в thinking.budget_tokens. Для OpenAI/DeepSeek поле сохраняется, но в настоящее время игнорируется сервером — рабочим параметром является reasoning_effort.

Provider Models vs Runtime Models

Qwen Code различает два типа конфигураций моделей:

Provider Model

• Определен в конфигурации modelProviders
• Имеет полный, атомарный пакет конфигурации
• При выборе его конфигурация применяется как непроницаемый слой
• Появляется в списке команды /model с полными метаданными (имя, описание, возможности)
• Рекомендуется для многомодельных рабочих процессов и согласованности в команде

Runtime Model

• Создается динамически при использовании raw ID моделей через CLI (--model), переменные окружения или настройки
• Не определен в modelProviders
• Конфигурация строится путем “проекции” через слои разрешения (CLI → env → settings → defaults)
• Автоматически захватывается как RuntimeModelSnapshot, когда обнаружена полная конфигурация
• Позволяет повторно использовать без повторного ввода учетных данных

Жизненный цикл RuntimeModelSnapshot

Когда вы настраиваете модель без использования modelProviders, Qwen Code автоматически создает RuntimeModelSnapshot для сохранения вашей конфигурации:

# Это создает RuntimeModelSnapshot с ID: $runtime|openai|my-custom-model
qwen --auth-type openai --model my-custom-model --openai-api-key $KEY --openai-base-url https://api.example.com/v1

Снимок:

• Захватывает ID модели, API-ключ, base URL и конфигурацию генерации
• Сохраняется между сессиями (хранится в памяти во время выполнения)
• Появляется в списке команды /model как runtime-опция
• На него можно переключиться с помощью /model $runtime|openai|my-custom-model

Ключевые различия

Когда что использовать

• Используйте Provider Models, когда: У вас есть стандартные модели, используемые всей командой, требуется согласованная конфигурация или вы хотите предотвратить случайные переопределения.
• Используйте Runtime Models, когда: Вы быстро тестируете новую модель, используете временные учетные данные или работаете с ad-hoc конечными точками.

Персистентность выбора и рекомендации

• /model и /auth сохраняют model.name (где применимо) и security.auth.selectedType в ближайшую доступную для записи область, которая уже определяет modelProviders; в противном случае они возвращаются к пользовательской области. Это поддерживает файлы рабочего пространства/пользователя в синхронизации с активным каталогом провайдеров.
• Без modelProviders резолвер смешивает слои CLI/env/settings, создавая Runtime Models. Это нормально для однопровайдерных настроек, но неудобно при частом переключении. Определяйте каталоги провайдеров, если многомодельные рабочие процессы распространены, чтобы переключения оставались атомарными, привязанными к источнику и отлаживаемыми.