#### :interrobang:Gemma-4 31B と 26B-A4B の推論での IndexError
31B と 26B で推論すると、このエラーが出ることがあります：
```python
File "/.../cache_utils.py", line 937, in update
keys, values = self.layers[layer_idx].update(...)
IndexError: list index out of range
```
原因は以下です：
```python
if hasattr(decoder_config, "num_kv_shared_layers"):
layer_types = layer_types[: -decoder_config.num_kv_shared_layers]
```
Gemma-4 31B と 26B-A4B は `num_kv_shared_layers = 0`で出荷されます。Python では `-0 == 0`、そのため `layer_types[:-0]` は `layer_types[:0] == []`に崩壊します。キャッシュは 0 個のレイヤー枠で構築され、最初の attention forward が `Cache.update`.
#### :no\_entry: `use_cache = True` だと E2B、E4B の生成が意味不明になっていました
[Issue を参照](https://github.com/huggingface/transformers/issues/45242) "\[Gemma 4] `use_cache=False` が attention 計算を壊し、ゴミの logits を生成する #45242"
Gemma-4 E2B と E4B は層間で KV 状態を共有します（`num_kv_shared_layers = 20` そして `18`）。キャッシュは、後続の層が再利用できるように、初期の層が KV を格納する唯一の場所です。 `use_cache=False` （すべての QLoRA チュートリアルで設定され、 `gradient_checkpointing=True` で強制されるように）、 `Gemma4TextModel.forward` はキャッシュ構築をスキップするため、KV 共有層は現在の隠れ状態から K と V をローカルで再計算することになります。logits はゴミになり、学習損失は発散します。
**修正前（`unsloth/gemma-4-E2B-it`、プロンプト「1+1 は？」）：**
```
use_cache=True -> '1 + 1 = **2**'
use_cache=False -> 'BROAD\肯. Specificallyboard K supposed\_n통 \'
max_abs_logit_diff: 48.937500
```
**修正後：**
```
use_cache=True -> '1 + 1 = **2**'
use_cache=False -> '1 + 1 = **2**'
max_abs_logit_diff: 0.000000 （ビット単位で完全一致、9 トークンすべてが同一）
```
#### :radio:Audio の float16 オーバーフロー
`Gemma4AudioAttention` は `config.attention_invalid_logits_value = -1e9` を `masked_fill` 呼び出しで使用します。fp16（Tesla T4）では、-1e9 は fp16 の最大値 65504 をオーバーフローし、次を引き起こします：
```python
RuntimeError: value cannot be converted to type c10::Half without overflow
```
これは `self.config.attention_invalid_logits_value` :
```python
attn_weights = attn_weights.masked_fill(
attention_mask.logical_not(), self.config.attention_invalid_logits_value
)
```
#### 💡Gemma-4 のヒント
1. もし **推論能力を維持したい** なら、推論スタイルの例と直接回答を混ぜることができます（少なくとも 75% は推論にしてください）。そうでなければ、完全に出力することもできます。\n\n使用してください `gemma-4` を非思考のチャットテンプレートに、 `gemma-4-thinking` を思考版に使ってください。\n大きい 26B と 31B には思考版を、 小さいものには非思考版を使ってください。
```python
from unsloth.chat_templates import get_chat_template
tokenizer = get_chat_template(
tokenizer,
chat_template = "gemma-4-thinking", # または "gemma-4"
)
```
2. 思考モードを有効にするには、 `enable_thinking = True / False` を `tokenizer.apply_chat_template`
思考有効：
processor.tokenizer.apply_chat_template([
{"role" : "user", "content" : "2+2 は？"},
], tokenize = False, enable_thinking = True, add_generation_prompt = True)
と表示されます `<|turn>system\n<|think|>\n<|turn>user\n2+2 は？\n<|turn>model\n`
思考無効：
```python
processor.tokenizer.apply_chat_template([
{"role" : "user", "content" : "2+2 は？"},
], tokenize = False, enable_thinking = False, add_generation_prompt = True)
```
と表示されます `<|turn>user\n2+2 は？\n<|turn>model\n<|channel>thought\n`
3. Gemma 4 は 140 言語をサポートしているため、多言語ファインチューニングに強力です。
4. トレーニングすることを推奨します **E4B QLoRA** よりも **E2B LoRA** 。E4B の方が大きく、量子化精度の差はごくわずかだからです。Gemma 4 E4B LoRA の方がさらに良いです。
5. ファインチューニング後は、 [GGUF](#saving-export-your-fine-tuned-model) （llama.cpp/Unsloth/Ollama など向け）
### ⚡クイックスタート
#### 🦥 Unsloth Studio ガイド
{% columns %}
{% column %}
Gemma 4 は [Unsloth Studio](/docs/jp/shii/studio.md)で実行・ファインチューニングできます。これはローカル AI 向けの新しいオープンソース Web UI です。
Unsloth Studio を使うと、モデルをローカルで **MacOS、Windows**、Linux 上で実行し、NVIDIA GPU で学習できます。Intel、MLX、AMD の学習サポートは今月中に来ます。
{% endcolumn %}
{% column %}
"""
sloth_link = "https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg"
messages = [{
"role" : "user",
"content": [
{ "type": "image", "image" : sloth_link },
{ "type": "text", "text" : "この動物はどの映画に登場しますか？" }
]
}]
# Unsloth の自動コンパイラのために 1 分待つ必要があるかもしれません
do_gemma_4_inference(messages, max_new_tokens = 256)
"""ナマケモノについて詩を書こう！"""
messages = [{
"role": "user",
"content": [{ "type" : "text",
"text" : "ナマケモノについて詩を書いてください。" }]
}]
do_gemma_4_inference(messages)
"""# Gemma 4 をファインチューニングしましょう！
今は選択機能を通じて vision と text の部分をファインチューニングできます。audio 部分もファインチューニング可能です。こちらも選択できるように取り組んでいます！
次に LoRA アダプターを追加して、更新するパラメータ数を少量に抑えます！
"""
model = FastModel.get_peft_model(
model,
finetune_vision_layers = False, # テキストのみならオフ！
finetune_language_layers = True, # オンのままにしてください！
finetune_attention_modules = True, # Attention は GRPO に有効
finetune_mlp_modules = True, # 常にオンのままにしてください！
r = 8, # 大きいほど精度は上がるが、過学習する可能性あり
lora_alpha = 8, # 推奨は少なくとも alpha == r
lora_dropout = 0,
bias = "none",
random_state = 3407,
)
"""
### データ準備
ここでは会話スタイルのファインチューニングに `Gemma-4` 形式を使います。[Maxime Labonne の FineTome-100k](https://huggingface.co/datasets/mlabonne/FineTome-100k) データセットを ShareGPT 形式で使用します。Gemma-4 は以下のようなマルチターン会話をレンダリングします：
```
<|turn>user
こんにちは
<|turn>model
やあ！
```
正しいチャットテンプレートを取得するために、私たちの `get_chat_template` 関数を使います。`zephyr, chatml, mistral, llama, alpaca, vicuna, vicuna_old, phi3, llama3, phi4, qwen2.5, gemma3, gemma-4` などをサポートしています。
"""
from unsloth.chat_templates import get_chat_template
tokenizer = get_chat_template(
tokenizer,
chat_template = "gemma-4-thinking",
)
"""データセットの最初の 3000 行を取得します"""
from datasets import load_dataset
dataset = load_dataset("mlabonne/FineTome-100k", split = "train[:3000]")
"""ここでは `standardize_data_formats` を使って、ファインチューニング用にデータセットを正しい形式へ変換してみます！"""
from unsloth.chat_templates import standardize_data_formats
dataset = standardize_data_formats(dataset)
"""100 行目がどのように見えるか見てみましょう！"""
dataset[100]
"""ここで会話に `Gemma-3` 用のチャットテンプレートを適用し、`text` に保存します。ファインチューニング中なので、`removeprefix('')` を使って `` トークンを削除します。Processor は学習前にこのトークンを追加し、モデルは 1 つだけを想定しています。"""
def formatting_prompts_func(examples):
convos = examples["conversations"]
texts = [tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False).removeprefix('') for convo in convos]
return { "text" : texts, }
dataset = dataset.map(formatting_prompts_func, batched = True)
"""チャットテンプレートがどう適用されたか見てみましょう！processor tokenizer が追加するので、`` トークンがないことに注目してください。"""
dataset[100]["text"]
"""
### モデルの学習
それではモデルを学習しましょう。ここでは速度向上のために 60 ステップだけ実行しますが、完全実行なら `num_train_epochs=1` を設定し、`max_steps=None` をオフにしてください。
"""
from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
model = model,
tokenizer = tokenizer,
train_dataset = dataset,
eval_dataset = None, # 評価も設定できます！
args = SFTConfig(
dataset_text_field = "text",
per_device_train_batch_size = 1,
gradient_accumulation_steps = 4, # バッチサイズを擬似的に再現するために GA を使う！
warmup_steps = 5,
# num_train_epochs = 1, # 1 回の完全学習ならこれを設定。
max_steps = 60,
learning_rate = 2e-4, # 長い学習では 2e-5 に下げる
logging_steps = 1,
optim = "adamw_8bit",
weight_decay = 0.001,
lr_scheduler_type = "linear",
seed = 3407,
report_to = "none", # TrackIO/WandB などを使用
),
)
"""Unsloth の `train_on_completions` メソッドも使って、アシスタント出力のみに学習し、ユーザー入力部分の損失は無視します。これはファインチューニングの精度向上に役立ちます！"""
from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
trainer,
instruction_part = "<|turn>user\n",
response_part = "<|turn>model\n",
)
"""指示部分のマスキングができているか確認しましょう！100 行目をもう一度表示します。サンプルには期待どおり `` が 1 つだけあることに注目してください！"""
tokenizer.decode(trainer.train_dataset[100]["input_ids"])
"""次にマスクされた例を表示しましょう。答えだけが存在するはずです："""
tokenizer.decode([tokenizer.pad_token_id if x == -100 else x for x in trainer.train_dataset[100]["labels"]]).replace(tokenizer.pad_token, " ")
"""# モデルを学習しましょう！
学習を再開するには、`trainer.train(resume_from_checkpoint = True)` を設定します
"""
trainer_stats = trainer.train()
````
{% endcode %}
{% hint style="info" %}
OOM したら：
* 下げる `per_device_train_batch_size` を **1** を、または `max_seq_length`.
* は維持 `use_`[`gradient_checkpointing`](/docs/jp/burogu/500k-context-length-fine-tuning.md#unsloth-gradient-checkpointing-enhancements)`="unsloth"` をオンにしてください（VRAM 使用量を減らし、コンテキスト長を延ばすために設計されています）。
{% endhint %}
**MoE 用のローダー例（bf16 LoRA）：**
```python
import os
import torch
from unsloth import FastModel
model, tokenizer = FastModel.from_pretrained(
model_name = "unsloth/Gemma-4-26B-A4B-it",
max_seq_length = 2048,
load_in_4bit = False, # MoE の QLoRA は推奨されません。dense 31B なら問題ありません
load_in_16bit = True, # bf16/16-bit LoRA
full_finetuning = False,
)
```
読み込んだら、LoRA アダプターを付けて、上の SFT 例と同様に学習します。
### 強化学習（RL）
これで Gemma 4 を RL、GSPO、GRPO などで学習できます。 [私たちの無料ノートブック](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_5_\(4B\)_Vision_GRPO.ipynb).
{% columns %}
{% column %}
Gemma 4 E2B RL は 9GB で動作します。
{% embed url="" %}
このノートブックの目的は、Gemma 4 に [GRPO](/docs/jp/meru/reinforcement-learning-rl-guide.md#from-rlhf-ppo-to-grpo-and-rlvr).
モデルは空のセルを埋める戦略を考案し、正しい配置と有効なパズルの完成に対して報酬を与えます。
vLLMではサポートされていなくても、UnslothでGemma 4 RLを実行できます。設定は次のとおりです `fast_inference=False` モデルの読み込み時に：
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
```python
from unsloth import FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
model_name="unsloth/gemma-4-E2B-it",
fast_inference=False,
)
```
### MoEファインチューニング（26B-A4B）
その **26B-A4B** このモデルはGemma 4ラインナップにおける速度／品質の中間地点です。これは **MoE** 各トークンごとにアクティブになるパラメータが一部のみのモデルなので、保守的なファインチューニング方針は次のとおりです：
* を使う **LoRA** フルファインチューニングではなく
* 優先する **16-bit / bf16 LoRA** メモリに余裕があれば
* まずは短いコンテキストと小さいrankから始める
* パイプラインが安定してからのみスケールアップする
最高品質が目標で、より多くのメモリがあるなら、次を使ってください： **31B** 代わりに。
### マルチモーダルファインチューニング（E2B / E4B）
なぜなら **E2B** そして **E4B** サポートしているため **画像** そして **音声**、これらがマルチモーダルファインチューニング向けの主要なGemma 4バリアントだからです。
* マルチモーダルモデルは次で読み込みます： `FastVisionModel`
* 維持する `finetune_vision_layers = False` 最初に
* 言語層、Attention層、MLP層のみをファインチューニングする
* 必要に応じて後からVision層やAudio層を有効にする
#### Gemma 4マルチモーダルLoRAの例：
{% code expandable="true" %}
````python
from unsloth import FastVisionModel # LLM向けにはFastLanguageModel
import torch
model, processor = FastVisionModel.from_pretrained(
"unsloth/gemma-4-26B-A4B-it",
load_in_4bit = True, # 4bitを使ってメモリ使用量を削減します。16bit LoRAならFalse。
use_gradient_checkpointing = "unsloth", # 長いコンテキストにはTrueまたは"unsloth"
)
"""ここでパラメータ効率の高いファインチューニングのためにLoRAアダプタを追加し、全モデルパラメータのわずか1%だけを効率的に学習できるようにします。
**[NEW]** さらに、Visionコンポーネントのみ、言語コンポーネントのみ、または両方をファインチューニングできます。加えて、Attentionモジュール、MLP層、またはその両方をファインチューニングすることも選べます！
"""
model = FastVisionModel.get_peft_model(
model,
finetune_vision_layers = True, # Vision層をファインチューニングしない場合はFalse
finetune_language_layers = True, # 言語層をファインチューニングしない場合はFalse
finetune_attention_modules = True, # Attention層をファインチューニングしない場合はFalse
finetune_mlp_modules = True, # MLP層をファインチューニングしない場合はFalse
r = 32, # 大きいほど精度は高いですが、過学習する可能性があります
lora_alpha = 32, # 推奨は少なくとも alpha == r
lora_dropout = 0,
bias = "none",
random_state = 3407,
use_rslora = False, # rank安定化LoRAをサポートしています
loftq_config = None, # LoftQにも対応しています
target_modules = "all-linear", # いまは任意です！必要ならリストを指定できます
)
"""
### データ準備
手書きの数式からサンプル化したデータセットを使います。目的は、これらの画像をコンピュータで読める形式、具体的にはLaTeXに変換してレンダリングできるようにすることです。これは複雑な式で特に有用です。
データセットは[こちら](https://huggingface.co/datasets/unsloth/LaTeX_OCR)からアクセスできます。完全なデータセットは[こちら](https://huggingface.co/datasets/linxy/LaTeX_OCR)です。
"""
from datasets import load_dataset
dataset = load_dataset("unsloth/LaTeX_OCR", split = "train")
"""データセットの概要を見てみましょう。2番目の画像と、それに対応するキャプションを確認します。"""
dataset
dataset[2]["image"]
dataset[2]["text"]
"""LaTeXはブラウザで直接レンダリングすることもできます！"""
from IPython.display import display, Math, Latex
latex = dataset[3]["text"]
display(Math(latex))
"""データセットを整形するには、すべてのVisionファインチューニングタスクが次の形式に従う必要があります：
```python
[
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
]
```
"""
instruction = "この画像のLaTeX表現を書いてください。"
def convert_to_conversation(sample):
conversation = [
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
{"role": "assistant", "content": [{"type": "text", "text": sample["text"]}]},
]
return {"messages": conversation}
pass
"""データセットをファインチューニング用の「正しい」形式に変換しましょう："""
converted_dataset = [convert_to_conversation(sample) for sample in dataset]
"""最初の例は次のような構造になります："""
converted_dataset[0]
"""Gemma 4の指示チャットテンプレートを取り出し、ベースモデルに適用しましょう"""
from unsloth import get_chat_template
processor = get_chat_template(
processor,
"gemma-4-thinking"
)
"""ファインチューニングの前に、ベースモデルの性能を評価してみましょう。このチャットテンプレートはまだ学習していないので、良い結果は期待していません。"""
image = dataset[2]["image"]
instruction = "この画像のLaTeX表現を書いてください。"
messages = [
{
"role": "user",
"content": [{"type": "image"}, {"type": "text", "text": instruction}],
}
]
input_text = processor.apply_chat_template(messages, add_generation_prompt = True)
inputs = processor(
image,
input_text,
add_special_tokens = False,
return_tensors = "pt",
).to("cuda")
from transformers import TextStreamer
text_streamer = TextStreamer(processor, skip_prompt = True)
result = model.generate(**inputs, streamer = text_streamer, max_new_tokens = 128,
use_cache = True, temperature = 1.0, top_p = 0.95, top_k = 64)
"""見てのとおり、まったくひどい結果です！指示に全然従っていません
### モデルの学習
ではモデルを学習しましょう。時間短縮のために60ステップだけ実行しますが、完全に回す場合は `num_train_epochs=1` に設定し、`max_steps=None` をオフにしてください。強化学習向けに `DPOTrainer` と `GRPOTrainer` もサポートしています！！
Visionファインチューニングのセットアップで役立つ、新しい `UnslothVisionDataCollator` を使います。
"""
from unsloth.trainer import UnslothVisionDataCollator
from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
model = model,
train_dataset = converted_dataset,
processing_class = processor.tokenizer,
data_collator = UnslothVisionDataCollator(model, processor),
args = SFTConfig(
per_device_train_batch_size = 1,
gradient_accumulation_steps = 4,
max_grad_norm = 0.3,
warmup_ratio = 0.03,
max_steps = 60,
# num_train_epochs = 2, # 完全な学習 रनでは max_steps の代わりにこちらを設定してください
learning_rate = 2e-4,
logging_steps = 1,
save_strategy = "steps",
optim = "adamw_8bit",
weight_decay = 0.001,
lr_scheduler_type = "cosine",
seed = 3407,
output_dir = "outputs",
report_to = "none", # Weights and Biases など向け
# Visionファインチューニングでは、以下の項目を必ず設定してください：
remove_unused_columns = False,
dataset_text_field = "",
dataset_kwargs = {"skip_prepare_dataset": True},
max_length = 2048,
)
)
trainer_stats = trainer.train()
````
{% endcode %}
#### 画像例の形式
覚えておいてください：Gemma 4のマルチモーダルプロンプトでは、画像を **先に** テキスト指示の前に置いてください。
{% code expandable="true" %}
```json
{
"messages": [
{
"role": "user",
"content": [
{"type": "image", "image": "/path/to/image OR object"},
{"type": "text", "text": "このレシートからすべてのテキストを抽出してください。明細、合計、店舗名、日付をJSONで返してください。"}
]
},
{
"role": "assistant",
"content": [
{"type": "text", "text": "{\"merchant\": \"Example Store\", \"total\": \"19.99\"}"}
]
}
]
}
```
{% endcode %}
#### 音声例の形式
音声は **E2B / E4B** のみです。クリップは短く、タスクに特化させてください。
{% code expandable="true" %}
```json
{
"messages": [
{
"role": "user",
"content": [
{"type": "audio", "audio": "/path/to/audio OR object"},
{"type": "text", "text": "次の英語の音声区間を英語テキストに書き起こしてください。転写のみを出力してください。"}
]
},
{
"role": "assistant",
"content": [
{"type": "text", "text": "Hello everyone and welcome back."}
]
}
]
}
```
{% endcode %}
### ファインチューニング済みモデルの保存／エクスポート
次の具体的な推論／デプロイガイドをご覧ください： [Unsloth Studio](/docs/jp/shii/studio/export.md), [llama.cpp](/docs/jp/ji-chu/inference-and-deployment/saving-to-gguf.md), [vLLM](/docs/jp/ji-chu/inference-and-deployment/vllm-guide.md), [llama-server](/docs/jp/ji-chu/inference-and-deployment/llama-server-and-openai-endpoint.md), [Ollama](/docs/jp/ji-chu/inference-and-deployment/saving-to-ollama.md) または [SGLang](/docs/jp/ji-chu/inference-and-deployment/sglang-guide.md).
#### GGUFに保存
UnslothはGGUFへの直接保存をサポートしています：
```python
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q4_k_m")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q8_0")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "f16")
```
またはGGUFをHugging Faceにプッシュ：
```python
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q4_k_m")
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q8_0")
```
書き出したモデルが別のランタイムで悪化する場合、Unslothは最も一般的な原因として次を挙げます： **推論時のチャットテンプレート／EOSトークンの誤り** （学習時と同じチャットテンプレートを使わなければなりません）。
詳細は推論ガイドをご覧ください：
{% columns %}
{% column width="50%" %}
{% content-ref url="/pages/d5ae43f1915ceda3d304ad7c413cb4efbe3d1a3f" %}
[推論とデプロイ](/docs/jp/ji-chu/inference-and-deployment.md)
{% endcontent-ref %}
{% content-ref url="/pages/9bfa988baa17c249340a58c332b8584f20d2537c" %}
[GGUF & llama.cpp](/docs/jp/ji-chu/inference-and-deployment/saving-to-gguf.md)
{% endcontent-ref %}
{% endcolumn %}
{% column width="50%" %}
{% content-ref url="/pages/a58a8ab897451539e1493312c6a640b4d5ee40b7" %}
[Model Export](/docs/jp/shii/studio/export.md)
{% endcontent-ref %}
{% content-ref url="/pages/0fde417d83989a8108b1d466ec2b53c46e9f4279" %}
[vLLM](/docs/jp/ji-chu/inference-and-deployment/vllm-guide.md)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}
### Gemma 4データのベストプラクティス
Gemma 4には、注意すべきいくつかのフォーマット上の詳細があります。
#### 1. 標準のチャットロールを使う
Gemma 4は標準の次を使います：
* `system`
* `user`
* `assistant`
これは、SFTデータセットを古いGemma固有のロール形式ではなく、通常のチャット形式で書くべきことを意味します。
#### 2. Thinkingモードは明示的です
SFT中にThinkingスタイルの挙動を保持したいなら：
* 形式を一貫させる
* どちらで学習するかを決める **表示される思考ブロック** または **最終回答のみ**
* する **ない** 互換性のない複数の思考フォーマットを同じデータセットに混在させる
ほとんどの本番向けアシスタントでは、最も簡単な設定は次のものだけでファインチューニングすることです： **最終的に表示される回答のみ**.
#### 3. マルチターンのルール
マルチターン会話では、次のものだけを保持してください： **最終的に表示される回答** 会話履歴に。 **ない** 以前の思考ブロックを後のターンに戻してはいけません。
---
# 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/jp/moderu/gemma-4/train.md?ask=&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.
