From 7c106000448737ff6bb0462a59490ab34e8f240c Mon Sep 17 00:00:00 2001 From: "Paul Gauthier (aider)" Date: Tue, 18 Mar 2025 12:32:22 -0700 Subject: [PATCH] docs: Update reasoning model settings documentation with compatibility details --- aider/website/docs/config/reasoning.md | 91 +++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 10 deletions(-) diff --git a/aider/website/docs/config/reasoning.md b/aider/website/docs/config/reasoning.md index 53e78b771..7d6a2a141 100644 --- a/aider/website/docs/config/reasoning.md +++ b/aider/website/docs/config/reasoning.md @@ -8,16 +8,38 @@ description: How to configure reasoning model settings from secondary providers. ![Thinking demo](/assets/thinking.jpg) -## Reasoning effort +## Reasoning settings + +Different models support different reasoning settings. Aider provides several ways to control reasoning behavior: + +### Reasoning effort You can use the `--reasoning-effort` switch to control the reasoning effort of models which support this setting. This switch is useful for OpenAI's reasoning models. -You can also use the `--thinking-tokens` switch to request +### Thinking tokens + +You can use the `--thinking-tokens` switch to request the model use a certain number of thinking tokens. This switch is useful for Sonnet 3.7. +### Model compatibility warnings + +Not all models support both settings. Aider will warn you when you use a setting that may not be supported by your chosen model: + +``` +Warning: The model claude-3-sonnet@20240229 may not support the 'reasoning_effort' setting. +Sending unsupported parameters can cause API calls to fail. Continue? [y/N] +``` + +You can disable these warnings with the `--no-check-model-accepts-settings` flag. + +Each model has a predefined list of supported settings in its configuration. For example: + +- OpenAI models generally support `reasoning_effort` +- Anthropic models (Claude) generally support `thinking_tokens` + ## Thinking tokens in XML tags @@ -40,6 +62,18 @@ Aider will display the thinking/reasoning output, but it won't be used for file editing instructions, etc. Aider will rely on the non-thinking output for instructions on how to make code changes, etc. +### Model-specific reasoning tags + +Different models use different XML tags for their reasoning: + +| Model | Reasoning Tag | +|-------|---------------| +| DeepSeek R1 | `think` | +| Deepseek V3 | `thinking` | +| Google Gemini | `reasoning` | + +When using custom or self-hosted models, you may need to specify the appropriate reasoning tag in your configuration. + ```yaml - name: fireworks_ai/accounts/fireworks/models/deepseek-r1 edit_format: diff @@ -55,22 +89,41 @@ Aider will rely on the non-thinking output for instructions on how to make code ## Reasoning model limitations -Many -"reasoning" models have restrictions on how they can be used: +Many "reasoning" models have restrictions on how they can be used: they sometimes prohibit streaming, use of temperature and/or the system prompt. Aider is configured to work properly with these models when served through major provider APIs. -You may need to [configure model settings](/docs/config/adv-model-settings.html) -if you are using them through another provider -and see errors related to temperature or system prompt. +### Model settings compatibility matrix -Include settings for your new provider in `.aider.model.setting.yml` file +Here's a summary of common reasoning settings compatibility: + +| Model Type | `reasoning_effort` | `thinking_tokens` | Notes | +|------------|-------------------|-------------------|-------| +| OpenAI reasoning models | ✅ | ❌ | Supports values 0-1 | +| Claude 3.7+ | ❌ | ✅ | Supports integer values | +| Claude 3.0-3.5 | ❌ | ❌ | Uses built-in reasoning | +| Google Gemini | ❌ | ❌ | Uses built-in reasoning | +| DeepSeek | ❌ | ❌ | Uses built-in reasoning | + +If you're using a model through a different provider (like Azure or custom deployment), +you may need to [configure model settings](/docs/config/adv-model-settings.html) +if you see errors related to temperature or system prompt. + +Include settings for your new provider in `.aider.model.settings.yml` file at the root of your project or in your home directory. ### Temperature, streaming and system prompt +Reasoning models often have specific requirements for these settings: + +| Setting | Description | Common Restrictions | +|---------|-------------|---------------------| +| `use_temperature` | Whether to use temperature sampling | Many reasoning models require this set to `false` | +| `streaming` | Whether to stream responses | Some reasoning models don't support streaming | +| `use_system_prompt` | Whether to use system prompt | Some reasoning models don't support system prompts | + You should find one of the existing model setting configuration entries for the model you are interested in, say o3-mini: @@ -91,8 +144,9 @@ for certain reasoning models: - `streaming` - `use_system_prompt` -Here's an example of -the settings to use o3-mini via Azure. +### Custom provider example + +Here's an example of the settings to use o3-mini via Azure. Note that aider already has these settings pre-configured, but they serve as a good example of how to adapt the main model settings for a different provider. @@ -106,3 +160,20 @@ settings for a different provider. editor_model_name: azure/gpt-4o editor_edit_format: editor-diff ``` + +### Accepting settings configuration + +Models define which reasoning settings they accept using the `accepts_settings` property: + +```yaml +- name: gpt-4o + edit_format: diff + weak_model_name: gpt-4o-mini + use_repo_map: true + editor_model_name: gpt-4o + editor_edit_format: editor-diff + accepts_settings: # <--- + - reasoning_effort # <--- +``` + +This tells Aider that the model accepts the `reasoning_effort` setting but not `thinking_tokens`, which is why you'll get a warning if you try to use `--thinking-tokens` with this model.