Провайдеры моделей

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here"
  },
  "modelProviders": {
    "openai": [
      {
        "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
          }
        }
      }
    ]
  }
}

Anthropic (anthropic)

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "modelProviders": {
    "anthropic": [
      {
        "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": [
      {
        "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
          }
        }
      }
    ]
  }
}

Локальные self-hosted модели (через OpenAI-совместимый API)

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

{
  "env": {
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed",
    "LMSTUDIO_API_KEY": "lm-studio"
  },
  "modelProviders": {
    "openai": [
      {
        "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
          }
        }
      }
    ]
  }
}

Для локальных серверов, не требующих аутентификации, можно использовать любое placeholder-значение для 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 Cloud Coding Plan
4. Выберите ваш регион
5. Введите API-ключ по запросу

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

Регионы

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

Регион выбирается во время аутентификации и сохраняется в settings.json в поле codingPlan.region. Чтобы сменить регион, повторно выполните команду /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": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "description": "Qwen3-Coder via Alibaba Cloud Coding Plan",
        "envKey": "YOUR_CUSTOM_ENV_KEY",
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
      }
    ]
  }
}

Слои разрешения и атомарность

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

*При наличии CLI-флаги аутентификации переопределяют настройки. В противном случае тип аутентификации определяется через security.auth.selectedType или неявное значение по умолчанию. Qwen OAuth и OpenAI — единственные типы аутентификации, доступные без дополнительной настройки.

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

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

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

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

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

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

   • Разрешение переходит к нижним слоям
   • Поля заполняются из CLI → env → настройки → значения по умолчанию
   • Это создает 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": [{
      "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, если не предоставлены)

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

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

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

Модели провайдеров vs Runtime-модели

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

Модель провайдера

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

Runtime-модель

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

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

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

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

Снимок (snapshot):

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

Ключевые отличия

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

• Используйте модели провайдеров, когда: у вас есть стандартные модели, общие для команды, требуется согласованность конфигураций или нужно предотвратить случайные переопределения
• Используйте Runtime-модели, когда: быстро тестируете новую модель, используете временные учетные данные или работаете с ad-hoc эндпоинтами

Сохранение выбора и рекомендации

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