> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/fr/modeles/deepseek-v4.1-flash.md).

# DeepSeek-V4.1-Flash : Guide d'exécution locale

Exécutez DeepSeek-V4.1-Flash-1017 localement avec les GGUF d'Unsloth et le déchargement n-gram d'Engram.

**DeepSeek-V4.1-Flash-1017** est la nouvelle mise à jour de V4.1-Flash, ce qui en fait le **plus puissant** modèle ouvert à ce jour pour le codage, les tâches agentiques et plus encore. Avec un contexte de 1 M, ses **552B** backbone + **196B Engram** paramètres prennent en charge le déchargement vers SSD pour réduire les besoins en RAM/VRAM. Ce guide montre comment exécuter DeepSeek-V4.1 localement avec [Unsloth Dynamic](/docs/fr/notions-de-base/dynamic-3.0-ggufs.md) GGUF.

Unsloth + llama.cpp permet \~**3x plus rapide** d'inférence DeepSeek-V4.1 que les autres dépôts axés CPU/VRAM/n-gram. Notre **250.4 GB** 1-bit `UD-IQ1_M` quantification atteint **88.2% d'accord top-1** par rapport au DeepSeek original et s'exécute localement sur des configurations avec 128GB+ de RAM. `UD-Q8_K_XL` (sans perte) est **508.4 GB**, tandis que `UD-Q4_K_XL` (quasi sans perte) est **500.7 GB**. GGUF : [**DeepSeek-V4.1-Flash-1017-GGUF**](https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF)

<a href="/pages/82884880ea897d182ea524477b935399ab04ad29#run-deepseek-v4.1-flash-1017-tutorials" class="button primary">Tutoriels pour exécuter DeepSeek-V4.1</a><a href="/docs/fr/modeles/deepseek-v4.1-flash.md#quantization-analysis" class="button secondary">Analyse des quantifications</a>

### ⚙️ Guide d'utilisation

**DeepSeek-V4.1-Flash-1017** associe MoE à **la mémoire conditionnelle Engram**: les n-grammes jusqu'à quatre jetons accèdent à quelques lignes de la table par jeton, de sorte que la table n'a pas besoin de rester en mémoire GPU. Il est préférable d'utiliser Unsloth pour l'inférence, car il permet jusqu'à **3x plus rapide** d'inférence DeepSeek-V4.1 que les autres dépôts axés CPU/VRAM/n-gram en optimisant par-dessus llama.cpp.

1-bit `UD-IQ1_S` fonctionnera sur des configurations avec 128GB de RAM comme un MacBook, un DGX Spark ou un RTX Spark, tandis que le 3 bits `UD-IQ3_XXS` fonctionnera sur des configurations avec 256GB de RAM comme un Mac Studio.

Comme les couches PLE / n-gram dans notre [Qwen3.8-Flash-Next](/docs/fr/modeles/qwen3.8-next.md) guide, la table Engram de 110.6–202.8 GB peut rester sur SSD via mmap. Les lignes se chargent à la demande dans le cache de l'OS, ce qui économise de la RAM/VRAM tout en conservant l'exigence complète de disque.

#### **Exigences de DeepSeek-V4.1-Flash-1017 :**

**Tableau : exigences matérielles** (RAM + VRAM, ou mémoire unifiée ; Engram sur SSD).

| 1-bit      | 2-bit      | 3-bit      | 4-bit  | 8-bit  |
| ---------- | ---------- | ---------- | ------ | ------ |
| 128–145 GB | 176–205 GB | 256–290 GB | 305 GB | 315 GB |

Les estimations prévoient environ 5–10 GB au-dessus des poids non Engram. Le runtime et le contexte peuvent nécessiter davantage.

**Stockage n-gram :** Les formats de recherche et les tailles des poids apparaissent ci-dessous. Les Go restants constituent la quantité minimale absolue de RAM/VRAM requise.

| Quant        | Format n-gram / Go | Go restants |
| ------------ | ------------------ | ----------- |
| UD-IQ1\_S    | IQ4\_NL / 110.6    | 122.4       |
| UD-IQ1\_M    | IQ4\_NL / 110.6    | 139.8       |
| UD-IQ2\_XXS  | Q5\_K / 135.2      | 165.3       |
| UD-Q2\_K\_XL | Q5\_K / 135.2      | 199.6       |
| UD-IQ3\_XXS  | Q6\_K / 161.3      | 233.5       |
| UD-IQ3\_S    | Q6\_K / 161.3      | 262.3       |
| UD-Q3\_K\_XL | MXFP8 / 202.8      | 282.3       |
| UD-Q4\_K\_XL | MXFP8 / 202.8      | 297.9       |
| UD-Q8\_K\_XL | MXFP8 / 202.8      | 305.6       |

### Paramètres recommandés

DeepSeek recommande temperature = 1.0, top-p = 1.0 et la désactivation de top-k et min-p :

| Paramètre                    | Réglage            |
| ---------------------------- | ------------------ |
| `temperature`                | `1.0`              |
| `top_p`                      | `1.0`              |
| Fenêtre de contexte maximale | `1,048,576` jetons |

DeepSeek recommande d'autoriser **au moins 256K jetons de sortie** pour sa configuration de génération longue.

### 📊 Analyse de la quantification

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FZbUjhpI7wJTjf3pM1uwu%2Fsize_vs_top1(1).png?alt=media&amp;token=4e133008-8026-4e93-baa7-d7f2e2b81ecc" alt=""><figcaption></figcaption></figure>

Les résultats sont comparés à la référence officielle de DeepSeek sur wiki1100 et long17k. Un KL plus faible signifie des probabilités du prochain jeton plus proches ; un top-1 plus élevé signifie davantage de prédictions correspondantes.

DeepSeek associe **MXFP4**, FP8 et BF16. Q4 et Q8 conservent **MXFP4** les experts et la même table Engram ; leurs étiquettes ne décrivent pas la précision de chaque tenseur. Q4 stocke de nombreux poids non experts en Q8\_0 ; Q8 utilise BF16.

Nous montrons aussi quand nous changeons la précision d'Engram de IQ4\_NL à Q5\_K, Q6\_K et MXFP8, et nous fournissons **des engrammes autonomes qui vous permettent de les mélanger selon vos besoins.**

| Quant        | Taille totale | wiki1100 KL / top-1 | long17k KL / top-1 |
| ------------ | ------------- | ------------------- | ------------------ |
| UD-IQ1\_S    | 233.0 GB      | 0.457 / 82.8%       | 0.364 / 85.1%      |
| UD-IQ1\_M    | 250.4 GB      | 0.314 / 87.1%       | 0.241 / 88.2%      |
| UD-IQ2\_XXS  | 300.5 GB      | 0.203 / 90.5%       | 0.142 / 91.2%      |
| UD-Q2\_K\_XL | 334.8 GB      | 0.138 / 91.5%       | 0.0879 / 93.3%     |
| UD-IQ3\_XXS  | 394.7 GB      | 0.0625 / 94.6%      | 0.043 / 95.1%      |
| UD-IQ3\_S    | 423.6 GB      | 0.0316 / 96.0%      | 0.0195 / 96.8%     |
| UD-Q3\_K\_XL | 485.1 GB      | 0.0204 / 96.5%      | 0.0114 / 97.4%     |
| UD-Q4\_K\_XL | 500.7 GB      | 9.00e-03 / 98.2%    | 4.46e-03 / 98.5%   |
| UD-Q8\_K\_XL | 508.4 GB      | 4.76e-03 / 98.5%    | 2.81e-03 / 98.7%   |

**Choisir une quantification :** IQ1\_S économise environ 54% d'espace disque par rapport à Q8. IQ1\_M ajoute 17.4 GB et améliore l'accord top-1 de 4.3 points sur wiki1100 et de 3.1 sur long17k. Les variantes IQ3 atteignent un accord de 94.6–96.8%.

#### **Effort de réflexion**

La réflexion est activée par défaut, avec `reasoning_effort=75` (« élevé »). Vous pouvez définir un entier de **1 à 100**. Des valeurs plus élevées demandent au modèle de raisonner plus en profondeur ; ce n'est pas une limite de jetons. Le modèle de gabarit inclus accepte aussi `faible` = 50, `moyen` = 62, `élevé` = 75 et `max` = 100.

Par exemple, ajoutez l'une de ces options à votre commande de lancement :

```bash
# Effort de réflexion par défaut
--chat-template-kwargs '{"reasoning_effort":75}'

# Effort de réflexion maximal
--chat-template-kwargs '{"reasoning_effort":100}'

# Désactiver la réflexion
--chat-template-kwargs '{"enable_thinking":false}'
```

## Exécuter **DeepSeek-V4.1-Flash-1017** Tutoriels :

Pour ce tutoriel, nous utilisons `UD-Q2_K_XL`. Unsloth sélectionne automatiquement les configurations de déchargement, de ngram, etc. les plus proches de l'optimal pour DeepSeek-V4.1, afin de garantir à votre configuration la vitesse la plus proche possible du meilleur niveau.

### 🦥 Guide Unsloth

[Unsloth Desktop](https://unsloth.ai/docs/desktop) est notre interface open source pour l'IA locale sur macOS, Windows et Linux. Vous pouvez rechercher et télécharger des GGUF, configurer le déchargement CPU et GPU, ajuster les paramètres d'inférence et connecter des outils depuis une seule application.

{% stepper %}
{% step %}

#### Installer Unsloth

La façon la plus simple de commencer est de télécharger [l'application Unsloth Desktop](/docs/fr/desktop.md). Fonctionne sur [macOS](/docs/fr/commencer/install/mac.md), [Windows](/docs/fr/commencer/install/windows-installation.md), et [Linux](/docs/fr/commencer/install/linux.md).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">Télécharger Unsloth</a>

* <i class="fa-apple">:apple:</i> [Télécharger pour macOS](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [Télécharger pour Windows](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [Télécharger pour Linux](https://unsloth.ai/download/linux)

Ou, si vous préférez l'installer manuellement :

{% tabs %}
{% tab title="Installation native" %}
**MacOS, Linux, WSL :**

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

**Windows :**

```powershell
irm https://unsloth.ai/install.ps1 | iex
```

{% endtab %}

{% tab title="Docker" %}
Le [L'image Docker Unsloth](https://hub.docker.com/r/unsloth/unsloth) `unsloth/unsloth` est disponible sur Docker. [Lire le guide.](https://unsloth.ai/docs/get-started/install/docker)
{% endtab %}

{% tab title="Homebrew" %}
Installer Unsloth Desktop :

{% code collapsedlinecount="10" %}

```bash
brew install --cask unsloth
```

{% endcode %}

Mettre à jour Unsloth Desktop :

```bash
brew upgrade --cask unsloth
```

{% endtab %}

{% tab title="WinGet" %}
Installer Unsloth Desktop :

```powershell
winget install --id UnslothAI.Unsloth -e
```

Mettre à jour Unsloth Desktop :

```powershell
winget upgrade --id UnslothAI.Unsloth -e
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Recherchez et téléchargez DeepSeek-V4.1-Flash-1017

Allez sur [Unsloth Chat](/docs/fr/nouveau/studio/chat.md) ou le hub de modèles, recherchez **DeepSeek-V4.1-Flash-1017** et sélectionnez [unsloth/DeepSeek-V4.1-Flash-1017-GGUF](https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF). Téléchargez la quantification souhaitée en utilisant les tailles et les exigences mémoire ci-dessus.
{% endstep %}

{% step %}

#### Exécuter DeepSeek-V4.1-Flash-1017

La réflexion est activée par défaut avec `75`, vous pouvez la modifier via notre commutateur. Unsloth sélectionne automatiquement les configurations de déchargement, de ngram, etc. les plus proches de l'optimal pour DeepSeek-V4.1, afin de garantir à votre configuration la vitesse la plus proche possible du meilleur niveau.

Pour plus d'informations, vous pouvez consulter notre [guide d'inférence Unsloth](/docs/fr/nouveau/studio/chat.md).

Avec UD-IQ1\_S, le téléchargement de 233.0 GB inclut une table n-gram Engram de 110.6 GB et 122.4 GB d'autres poids. Utilisez le chargement à la demande d'Engram pour conserver la table de recherche sur SSD, avec de la RAM/VRAM supplémentaire pour les lignes mises en cache, le contexte et les tampons d'exécution. Suivez le Guide d'utilisation ci-dessus pour les besoins en mémoire.
{% endstep %}

{% step %}

#### Servir DeepSeek-V4.1-Flash-1017 avec l'API Unsloth

Vous pouvez utiliser `la commande unsloth run` et servir DeepSeek-V4.1-Flash-1017 via une API en utilisant `llama-server` les indicateurs d'exécution, y compris le dimensionnement du contexte, les couches GPU, le threading, l'échantillonnage, la mise en réseau et la configuration des outils. Pour plus d'informations, consultez nos [docs de l'API](/docs/fr/notions-de-base/api.md) ou [unsloth start](/docs/fr/integrations/unsloth-start.md).

{% code overflow="wrap" %}

```bash
unsloth run --model unsloth/DeepSeek-V4.1-Flash-1017-GGUF:UD-Q2_K_XL \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --min-p 0.0 \\
    --chat-template-kwargs '{"reasoning_effort":75}'
```

{% endcode %}

Utilisez un runtime avec DeepSeek-V4.1-1017 et la prise en charge du chargement à la demande d'Engram. Appliquez les paramètres de déchargement SSD et de mémoire du Guide d'utilisation lorsque vous conservez la table n-gram sur disque.
{% endstep %}

{% step %}

#### Unsloth est désormais prêt

Vous pouvez connecter DeepSeek-V4.1-Flash-1017 à vos outils via Unsloth Desktop. Unsloth prend également en charge les flux de travail suivants :

* **Connecter des outils :** [Claude Code](/docs/fr/notions-de-base/claude-code.md), [Codex](/docs/fr/notions-de-base/codex.md), [recherche web](/docs/fr/nouveau/studio/chat.md#advanced-web-search), [MCP](/docs/fr/notions-de-base/mcp.md) et plus encore
* **Entraîner des modèles :** Affiner d'autres modèles pris en charge : texte, diffusion, [intégration](/docs/fr/notions-de-base/embedding-finetuning.md)et plus encore
* **Générer des médias :** Créer et entraîner [des images](/docs/fr/notions-de-base/diffusion-image.md), des vidéos, [TTS](/docs/fr/notions-de-base/text-to-speech-tts-fine-tuning.md) localement

<div align="center"><figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FYShiiub5gs5pCQLX6d4U%2FScreenshot%202026-08-15%20at%2012.18.24%E2%80%AFAM.png?alt=media&amp;token=d6996797-a144-4113-b4c3-155cca6c39a0" alt="Unsloth Desktop Agents settings interface example" width="563"><figcaption><p>Paramètres Agents de Unsloth Desktop (exemple d'interface). Sélectionnez DeepSeek-V4.1-Flash-1017 et votre quantification téléchargée lors de la connexion d'un outil.</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 Exécuter DeepSeek-V4.1-Flash dans llama.cpp

{% stepper %}
{% step %}
Nous devons utiliser notre PR spécifique de llama.cpp [ici](https://github.com/ggml-org/llama.cpp/pull/30817). Vous pouvez également suivre les instructions de compilation ci-dessous. Modifiez `-DGGML_CUDA=ON` en `-DGGML_CUDA=OFF` si vous n'avez pas de GPU ou si vous souhaitez simplement une inférence CPU. **Pour les appareils Apple Mac / Metal**, définissez `-DGGML_CUDA=OFF` puis continuez normalement - la prise en charge Metal est activée par défaut.

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev git -y
git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/30817/head:deepseek41
git -C llama.cpp checkout deepseek41
cmake llama.cpp -B llama.cpp/build \\
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

{% endstep %}

{% step %}
Pour exécuter le modèle, vous pouvez faire :

```bash
pip install -U "huggingface_hub[cli]"
hf download unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
    --local-dir unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
    --include "*UD-Q2_K_XL*"
```

Conservez les sept shards dans le même dossier et pointez `--model` vers le premier shard. llama.cpp charge automatiquement les shards restants.
{% endstep %}

{% step %}
Ensuite, pour l'exécuter :

```bash
./llama.cpp/llama-cli \\
    --model unsloth/DeepSeek-V4.1-Flash-1017-GGUF/UD-Q2_K_XL/DeepSeek-V4.1-Flash-1017-UD-Q2_K_XL-00001-of-00007.gguf \\
    --temp 1.0 \\
    --top-p 1.0 \\
    --top-k 0 \\
    --min-p 0.0 \\
    --chat-template-kwargs '{"reasoning_effort":75}' \\
    --load-mode mmap \\
    --lazy-mode on \\
    --override-tensor "per_layer_token_embd.weight=CPU"
```

Cet exemple charge la table n-gram Engram depuis le SSD à la demande. Conservez `--load-mode mmap` et `--lazy-mode on` activés pour le déchargement SSD.
{% endstep %}
{% endstepper %}

### ⚡**DSpark** - Décodage spéculatif

DeepSeek-V4.1 inclut **DSpark**, une architecture de décodage spéculatif qui propose plusieurs jetons avant que le modèle principal ne les vérifie. Elle est distincte de la table de recherche n-gram Engram : **Engram fournit une mémoire apprise ; DSpark accélère le décodage**. L'option de décodage spéculatif n-gram portant un nom similaire est également une fonctionnalité différente.

Pour DSpark, associez le modèle principal à un **drafter V4.1-1017 correspondant** et à un runtime prenant en charge DSpark. Faites correspondre les versions du drafter et du checkpoint principal, et réservez de la mémoire supplémentaire pour le drafter. Les exemples CLI et serveur de ce guide utilisent le décodage ordinaire.

**DSpark permet à l'inférence pour DeepSeek-V4.1-Flash-GGUF d'être environ 1.3 à 1.5x plus rapide pour le décodage !**

Nous fournissons un module DSpark Q8\_0 à 8GB, et un BF16 complet à 8.5GB.

### :checkered\_flag:Mélanger et assortir l'Engram

Vous pouvez également modifier la précision d'Engram pour DeepSeek-V4.1 selon vos souhaits.

| Précision d'Engram | Taille (Go) |
| ------------------ | ----------- |
| MXFP8 (original)   | 202.8 GB    |
| Q6\_K              | 161.3 GB    |
| Q5\_K              | 135.2 GB    |
| IQ4\_NL            | 110.6 GB    |

Par exemple, après avoir téléchargé la quantification dynamique 1-bit IQ1\_S qui utilise par défaut l'Engram IQ4\_NL, vous pouvez la remplacer par celle en MXFP8 en téléchargeant uniquement l'Engram MXFP8 à <https://huggingface.co/unsloth/DeepSeek-V4.1-Flash-1017-GGUF/tree/main/engram> appelé `DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file` Pour ce faire, suivez le script ci-dessous :

```bash
# 1. récupérer la table + le script
hf download unsloth/DeepSeek-V4.1-Flash-1017-GGUF \\
  --include "engram/*MXFP8*" "engram/set_split.py" --local-dir .

# 2. le marquer comme shard 5 sur 5 (emplacement de table de UD-IQ1_S)
python engram/set_split.py engram/DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file 5 5

# 3. garder l'ancienne table de côté, puis renommer la nouvelle au nom du shard de la table
mv UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00005-of-00005.gguf UD-IQ1_S/engram-IQ4_NL.bak
mv engram/DeepSeek-V4.1-Flash-1017-engram-MXFP8.gguf_file \\
   UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00005-of-00005.gguf

# 4. exécuter comme d'habitude
llama-server -m UD-IQ1_S/DeepSeek-V4.1-Flash-1017-UD-IQ1_S-00001-of-00005.gguf
```

## 📊 Benchmarks

### **Évaluations GGUF KLD et top-1 %**

Nos quantifications couvrent 82.8–98.5% d'accord top-1 par rapport à la référence F32 officielle sur wiki1100 et 85.1–98.7% sur long17k. UD-Q4\_K\_XL économise 7.7 GB par rapport à UD-Q8\_K\_XL, avec un écart d'accord de 0.3 point de pourcentage sur wiki1100 et de 0.2 sur long17k. Q8 a également une divergence KL plus faible sur les deux ensembles.

**Nous modifions également la précision de la table Engram de IQ4\_NL à Q5\_K, Q6\_K et MXFP8, et montrons comment la KLD est affectée**

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FdIFvyiUQafZ2upn6VdhJ%2Fsize_vs_kld(1).png?alt=media&amp;token=e5d14eab-9143-4d0a-b1a6-f5427d995808" alt=""><figcaption></figcaption></figure>

### **Benchmarks officiels**

DeepSeek rapporte les résultats suivants pour **V4.1-Flash-1017** par rapport à la version V4.1-Flash précédente. Il s'agit des résultats officiels du modèle, et non de mesures des GGUF de ce guide. Source : [fiche modèle 1017 de DeepSeek](https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash-1017).

| Benchmark                    | V4.1-Flash-1017 | V4.1-Flash   |
| ---------------------------- | --------------- | ------------ |
| HLE sans outils              | 42.6 (44.0†)    | 36.8 (39.1†) |
| Terminal-Bench 4.0           | 42.3            | 31.2         |
| DeepSWE v1.1                 | 77.0            | 74.2         |
| ProgramBench                 | 29.1            | 20.3         |
| NL2Repo-Bench                | 68.2            | 65.4         |
| Automation-Bench v1.0.6      | 60.5            | 54.8         |
| Agents' Last Exam            | 35.4            | 31.8         |
| Apex Bench v1.1              | 72.1            | 64.6         |
| Chartography (avec outils)   | 83.0            | 78.9         |
| BabyVision (avec outils)     | 92.5            | 89.6         |
| ZeroBench-main (avec outils) | 51.0            | 49.0         |

† Sous-ensemble textuel uniquement de HLE. DeepSeek utilise le harness Claude Code pour Terminal-Bench 4.0 et Mini-SWE-V2 pour DeepSWE v1.1. Les scores dépendent de la configuration d'évaluation, de l'effort de réflexion et du budget de contexte.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/fr/modeles/deepseek-v4.1-flash.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.