> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/comfyui.md).

# ComfyUI

在 Clore.ai 上使用 ComfyUI 的节点式 Stable Diffusion 界面

基于节点的 Stable Diffusion 界面，在 CLORE.AI GPU 上拥有极致灵活性。

{% hint style="success" %}
所有示例都可以在通过以下方式租用的 GPU 服务器上运行 [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

## 服务器要求

| 参数   | 最低        | 推荐     |
| ---- | --------- | ------ |
| 内存   | 16GB      | 32GB以上 |
| 显存   | 8GB（SDXL） | 12GB+  |
| 网络   | 500Mbps   | 1Gbps+ |
| 启动时间 | 5-10 分钟   | -      |

{% hint style="warning" %}
**启动时间：** 首次启动会下载依赖和模型（取决于网络速度，需 5-10 分钟）。此时出现 HTTP 502 是正常的。
{% endhint %}

{% hint style="danger" %}
**重要：** 使用 FLUX 模型的 ComfyUI 需要 16GB+ VRAM。对于带 ControlNet 的 SDXL，请确保至少有 10GB VRAM。
{% endhint %}

## 为什么选择 ComfyUI？

* **基于节点的工作流** - 用于图像生成的可视化编程
* **最大控制** - 对流水线的每一步进行精细调整
* **高效** - 比其他方案更低的 VRAM 占用
* **可扩展** - 庞大的自定义节点生态系统
* **工作流共享** - 以 JSON 导入/导出

## 在 CLORE.AI 上快速部署

**Docker 镜像：**

```
yanwk/comfyui-boot:cu130-slim
```

**端口：**

```
22/tcp
8188/http
```

**环境变量：**

```
CLI_ARGS=--listen 0.0.0.0
```

### 验证是否正常工作

部署后，找到你的 `http_pub` URL 在 **我的订单**:

```bash
# 检查 UI 是否可访问（首次运行可能需要 5-10 分钟）
curl https://your-http-pub.clorecloud.net/
```

{% hint style="info" %}
如果 15 分钟以上仍然出现 HTTP 502，请检查：

1. 服务器拥有 16GB+ RAM
2. 服务器为 SDXL 配备 8GB+ VRAM，为 FLUX 配备 16GB+ VRAM
3. 网络速度足以下载模型
   {% endhint %}

## 访问你的服务

在 CLORE.AI 上部署时，请通过以下方式访问 ComfyUI： `http_pub` URL：

* **Web UI：** `https://your-http-pub.clorecloud.net/`
* **API：** `https://your-http-pub.clorecloud.net/prompt`
* **WebSocket：** `wss://your-http-pub.clorecloud.net/ws`

{% hint style="info" %}
全部 `localhost:8188` 以下示例在通过 SSH 连接时可用。对于外部访问，请替换为你的 `https://your-http-pub.clorecloud.net/` URL。
{% endhint %}

## 安装

### 使用 Docker（推荐）

```bash
docker run -d --gpus all \\
  -p 8188:8188 \\
  -v comfyui-data:/root \\
  -e CLI_ARGS="--listen 0.0.0.0" \\
  yanwk/comfyui-boot:cu130-slim
```

### 手动安装

```bash
# 克隆仓库
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 安装带 CUDA 的 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# 安装依赖
pip install -r requirements.txt

# 运行
python main.py --listen 0.0.0.0
```

## 目录结构

```
ComfyUI/
├── models/
│   ├── checkpoints/     # SD 模型（.safetensors）
│   ├── loras/           # LoRA 模型
│   ├── vae/             # VAE 模型
│   ├── controlnet/      # ControlNet 模型
│   ├── upscale_models/  # 放大模型
│   └── clip/            # CLIP 模型
├── input/               # 输入图像
├── output/              # 生成图像
└── custom_nodes/        # 扩展
```

## 下载模型

### Stable Diffusion 检查点

```bash
cd ComfyUI/models/checkpoints

# SDXL 基础版
wget https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors

# SDXL 精修器
wget https://huggingface.co/stabilityai/stable-diffusion-xl-refiner-1.0/resolve/main/sd_xl_refiner_1.0.safetensors

# SD 1.5（更小、更快）
wget https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned.safetensors

# Realistic Vision（照片级真实感）
wget https://huggingface.co/SG161222/Realistic_Vision_V6.0_B1_noVAE/resolve/main/Realistic_Vision_V6.0_B1_fp16.safetensors
```

### VAE

```bash
cd ComfyUI/models/vae

# SDXL VAE
wget https://huggingface.co/stabilityai/sdxl-vae/resolve/main/sdxl_vae.safetensors

# SD 1.5 VAE（颜色更好）
wget https://huggingface.co/stabilityai/sd-vae-ft-mse-original/resolve/main/vae-ft-mse-840000-ema-pruned.safetensors
```

### LoRA

```bash
cd ComfyUI/models/loras

# 从 CivitAI 或 HuggingFace 下载
# 将 .safetensors 文件放在这里
```

## 基础工作流

### 文生图

1. 添加节点：
   * **加载检查点** → 选择模型
   * **CLIP 文本编码** （x2）→ 正向与负向提示词
   * **空潜空间图像** → 设置尺寸
   * **KSampler** → 连接全部
   * **VAE 解码** → 潜空间转图像
   * **保存图像** → 输出
2. 连接：

```
[Checkpoint] → MODEL → [KSampler]
[Checkpoint] → CLIP → [CLIP Text Encode +]
[Checkpoint] → CLIP → [CLIP Text Encode -]
[Checkpoint] → VAE → [VAE Decode]
[Text Encode +] → CONDITIONING → [KSampler]
[Text Encode -] → CONDITIONING → [KSampler]
[Empty Latent] → LATENT → [KSampler]
[KSampler] → LATENT → [VAE Decode]
[VAE Decode] → IMAGE → [Save Image]
```

### 图生图

替换 **空潜空间图像** 为：

1. **加载图像** → 你的源图像
2. **VAE 编码** → 转换为潜空间
3. 调整 **降噪** 在 KSampler 中（0.5-0.8）

## ComfyUI 管理器

ComfyUI Manager 是一个 **必备扩展** 它提供一个用于安装、更新和管理自定义节点的 GUI。它是扩展 ComfyUI 的标准方式。

### 安装

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
# 重启 ComfyUI — 工具栏中会出现一个“Manager”按钮
```

### 使用 ComfyUI Manager

重启后， **Manager** 按钮会出现在 ComfyUI 界面的右上角。

**主要特性：**

| 功能      | 如何访问                 |
| ------- | -------------------- |
| 安装自定义节点 | Manager → 安装自定义节点    |
| 更新所有节点  | Manager → 更新全部       |
| 禁用/启用节点 | Manager → 自定义节点管理器   |
| 安装缺失节点  | Manager → 安装缺失的自定义节点 |
| 获取模型信息  | Manager → 模型管理器      |
| 恢复快照    | Manager → 快照管理器      |

**工作流：安装新的节点包**

1. 点击 **Manager** 按钮
2. 选择 **安装自定义节点**
3. 按名称搜索（例如“FLUX”、“AnimateDiff”）
4. 点击 **安装** 在所需的节点包上
5. 点击 **重启** 在提示时
6. 新节点会出现在右键添加菜单中

**自动安装缺失节点：** 当你导入使用你没有的节点的工作流 JSON 时，Manager 会检测到它们，并提供通过以下方式自动安装： **安装缺失的自定义节点**.

### 保持节点更新

```bash
# 通过 CLI（GUI 的替代方式）：
cd ComfyUI/custom_nodes/ComfyUI-Manager
git pull

# 或在 UI 中使用 Manager → 更新全部
```

***

## ComfyUI 中的 FLUX 工作流

FLUX 使用与标准 SD 模型不同的节点结构。以下是完整的 FLUX.1-dev 工作流。

### 所需文件

在运行工作流之前，下载：

```bash
# FLUX 模型（dev 或 schnell）
cd ComfyUI/models/unet
wget https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/flux1-dev.safetensors

# 文本编码器
cd ../clip
wget https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/clip_l.safetensors
wget https://huggingface.co/comfyanonymous/flux_text_encoders/resolve/main/t5xxl_fp16.safetensors

# VAE
cd ../vae
wget https://huggingface.co/black-forest-labs/FLUX.1-dev/resolve/main/ae.safetensors
```

### FLUX.1-dev 工作流 JSON

另存为 `flux_dev_workflow.json` 并通过以下方式导入 **加载** ComfyUI 中的按钮：

```json
{
  "last_node_id": 12,
  "last_link_id": 20,
  "nodes": [
    {
      "id": 1,
      "type": "UNETLoader",
      "pos": [100, 100],
      "size": [300, 60],
      "inputs": [],
      "outputs": [{"name": "MODEL", "type": "MODEL", "links": [1]}],
      "properties": {},
      "widgets_values": ["flux1-dev.safetensors", "default"]
    },
    {
      "id": 2,
      "type": "DualCLIPLoader",
      "pos": [100, 200],
      "size": [350, 80],
      "inputs": [],
      "outputs": [{"name": "CLIP", "type": "CLIP", "links": [2, 3]}],
      "properties": {},
      "widgets_values": ["clip_l.safetensors", "t5xxl_fp16.safetensors", "flux"]
    },
    {
      "id": 3,
      "type": "CLIPTextEncode",
      "pos": [500, 150],
      "size": [425, 180],
      "inputs": [{"name": "clip", "type": "CLIP", "link": 2}],
      "outputs": [{"name": "CONDITIONING", "type": "CONDITIONING", "links": [4]}],
      "properties": {},
      "widgets_values": ["令人惊叹的照片级真实风景，黄金时刻光照，8K"]
    },
    {
      "id": 4,
      "type": "EmptySD3LatentImage",
      "pos": [100, 350],
      "size": [300, 100],
      "inputs": [],
      "outputs": [{"name": "LATENT", "type": "LATENT", "links": [5]}],
      "properties": {},
      "widgets_values": [1024, 1024, 1]
    },
    {
      "id": 5,
      "type": "ModelSamplingFlux",
      "pos": [500, 350],
      "size": [300, 80],
      "inputs": [{"name": "model", "type": "MODEL", "link": 1}],
      "outputs": [{"name": "MODEL", "type": "MODEL", "links": [6]}],
      "properties": {},
      "widgets_values": [1.15, 0.5, 1024, 1024]
    },
    {
      "id": 6,
      "type": "KSampler",
      "pos": [850, 250],
      "size": [350, 240],
      "inputs": [
        {"name": "model", "type": "MODEL", "link": 6},
        {"name": "positive", "type": "CONDITIONING", "link": 4},
        {"name": "negative", "type": "CONDITIONING", "link": 7},
        {"name": "latent_image", "type": "LATENT", "link": 5}
      ],
      "outputs": [{"name": "LATENT", "type": "LATENT", "links": [8]}],
      "properties": {},
      "widgets_values": [42, "fixed", 20, 3.5, "euler", "simple", 1.0]
    },
    {
      "id": 7,
      "type": "CLIPTextEncode",
      "pos": [500, 500],
      "size": [300, 60],
      "inputs": [{"name": "clip", "type": "CLIP", "link": 3}],
      "outputs": [{"name": "CONDITIONING", "type": "CONDITIONING", "links": [7]}],
      "properties": {},
      "widgets_values": [""]
    },
    {
      "id": 8,
      "type": "VAELoader",
      "pos": [100, 500],
      "size": [300, 60],
      "inputs": [],
      "outputs": [{"name": "VAE", "type": "VAE", "links": [9]}],
      "properties": {},
      "widgets_values": ["ae.safetensors"]
    },
    {
      "id": 9,
      "type": "VAEDecode",
      "pos": [1250, 300],
      "size": [210, 46],
      "inputs": [
        {"name": "samples", "type": "LATENT", "link": 8},
        {"name": "vae", "type": "VAE", "link": 9}
      ],
      "outputs": [{"name": "IMAGE", "type": "IMAGE", "links": [10]}],
      "properties": {}
    },
    {
      "id": 10,
      "type": "SaveImage",
      "pos": [1500, 300],
      "size": [300, 270],
      "inputs": [{"name": "images", "type": "IMAGE", "link": 10}],
      "outputs": [],
      "properties": {},
      "widgets_values": ["flux_output"]
    }
  ],
  "links": [
    [1, 1, 0, 5, 0, "MODEL"],
    [2, 2, 0, 3, 0, "CLIP"],
    [3, 2, 0, 7, 0, "CLIP"],
    [4, 3, 0, 6, 1, "CONDITIONING"],
    [5, 4, 0, 6, 3, "LATENT"],
    [6, 5, 0, 6, 0, "MODEL"],
    [7, 7, 0, 6, 2, "CONDITIONING"],
    [8, 6, 0, 9, 0, "LATENT"],
    [9, 8, 0, 9, 1, "VAE"],
    [10, 9, 0, 10, 0, "IMAGE"]
  ],
  "groups": [],
  "config": {},
  "extra": {"ds": {"scale": 0.8, "offset": [0, 0]}},
  "version": 0.4
}
```

### FLUX.1-schnell 工作流（4 步）

对于 schnell，请修改上方 JSON 中的 KSampler 设置：

* `推理步数`: `4`
* `cfg`: `1.0`
* `调度器`: `"simple"`
* 模型文件： `flux1-schnell.safetensors`

或者通过 UI 设置：KSampler → 步数： **4**，cfg： **1.0**，采样器： **euler**，调度器： **simple**

### 关键节点差异：FLUX vs SD

| 节点    | SD/SDXL        | FLUX                            |
| ----- | -------------- | ------------------------------- |
| 模型加载器 | 加载检查点          | UNETLoader                      |
| 文本编码器 | CLIPTextEncode | DualCLIPLoader + CLIPTextEncode |
| 潜空间   | 空潜空间图像         | EmptySD3LatentImage             |
| 额外    | —              | ModelSamplingFlux               |
| 负向提示词 | 必需             | 可选（留空）                          |

***

## 必备自定义节点

### 推荐的节点包

| 节点包                      | GitHub                                  | 使用场景               |
| ------------------------ | --------------------------------------- | ------------------ |
| **ComfyUI-Manager**      | ltdrdata/ComfyUI-Manager                | 安装并管理所有其他节点        |
| **ComfyUI-FLUX**         | XLabs-AI/x-flux-comfyui                 | FLUX ControlNet 节点 |
| **was-node-suite**       | WASasquatch/was-node-suite-comfyui      | 100+ 实用节点          |
| ComfyUI-Impact-Pack      | ltdrdata/ComfyUI-Impact-Pack            | 人脸检测、SAM、ADetailer |
| ComfyUI-Inspire-Pack     | ltdrdata/ComfyUI-Inspire-Pack           | 高级采样器、工作流          |
| ComfyUI-AnimateDiff      | Kosinkadink/ComfyUI-AnimateDiff-Evolved | 视频 / 动画生成          |
| ComfyUI-VideoHelperSuite | Kosinkadink/ComfyUI-VideoHelperSuite    | 视频 I/O 处理          |
| ComfyUI-GGUF             | city96/ComfyUI-GGUF                     | 运行量化的 GGUF 模型      |
| ComfyUI-KJNodes          | kijai/ComfyUI-KJNodes                   | 实用与遮罩节点            |
| rgthree-comfy            | rgthree/rgthree-comfy                   | 工作流辅助，更好的 UI       |

### ComfyUI-FLUX（XLabs-AI）

在 ComfyUI 中为 FLUX 添加 ControlNet 支持：

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/XLabs-AI/x-flux-comfyui
cd x-flux-comfyui
pip install -r requirements.txt
```

添加节点： `应用 ControlNet（FLUX）`, `加载 ControlNet 模型（FLUX）`, `XFlux 采样器`

### was-node-suite

用于高级工作流的 100 多个实用节点：

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/WASasquatch/was-node-suite-comfyui
cd was-node-suite-comfyui
pip install -r requirements.txt
```

关键节点：图像批处理、文本操作、图像分析、缓存节点、总线节点、放大、遮罩操作

### 通过 Manager 安装

1. 点击 **Manager** 按钮
2. **安装自定义节点**
3. 搜索并安装
4. 重启 ComfyUI

## 高级工作流

### ControlNet

```bash
# 下载 ControlNet 模型
cd ComfyUI/models/controlnet

# Canny
wget https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_canny.pth

# Depth
wget https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11f1p_sd15_depth.pth

# OpenPose
wget https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_openpose.pth
```

工作流：

1. 加载图像 → Canny 边缘检测器
2. 应用 ControlNet → KSampler
3. 使用姿态/边缘引导生成

### 放大

```bash
# 下载放大器
cd ComfyUI/models/upscale_models
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth
```

工作流：

1. 以较低分辨率生成图像（768x768）
2. 放大图像（模型）节点
3. 可选：进行 img2img 细节增强

### SDXL + Refiner

1. 使用 SDXL 基础模型生成（步数 1-20）
2. 将潜变量传递给 SDXL refiner（步数 21-30）
3. VAE 解码最终结果

## 键盘快捷键

| 按键                 | 操作           |
| ------------------ | ------------ |
| `Ctrl+Enter`       | 排队提示词        |
| `Ctrl+Shift+Enter` | 将提示词加入队列（前端） |
| `Ctrl+Z`           | 撤销           |
| `Ctrl+Y`           | 重做           |
| `Ctrl+S`           | 保存工作流        |
| `Ctrl+O`           | 加载工作流        |
| `Ctrl+A`           | 全选           |
| `Delete`           | 删除所选         |
| `Ctrl+M`           | 静音节点         |
| `Ctrl+B`           | 旁路节点         |

## API 使用

### 排队提示词

```python
import json
import urllib.request

# 进行外部访问时，请使用你的 http_pub URL：
SERVER = "your-http-pub.clorecloud.net"
# 或通过 SSH：SERVER = "localhost:8188"

def queue_prompt(prompt, server=SERVER):
    data = json.dumps({"prompt": prompt}).encode('utf-8')
    req = urllib.request.Request(f"https://{server}/prompt", data=data)
    urllib.request.urlopen(req)

# 加载工作流 JSON 并排队
with open("workflow.json") as f:
    workflow = json.load(f)
queue_prompt(workflow)
```

### 用于进度的 WebSocket

```python
import websocket
import json

# 进行外部访问时，请使用带有你的 http_pub URL 的 wss://
ws = websocket.WebSocket()
ws.connect(f"wss://{SERVER}/ws")

while True:
    msg = json.loads(ws.recv())
    if msg['type'] == 'progress':
        print(f"步骤 {msg['data']['value']}/{msg['data']['max']}")
    elif msg['type'] == 'executed':
        print("完成！")
        break
```

## 性能提示

1. **启用 --lowvram** 适用于 <8GB VRAM
2. **尽可能使用 fp16** 模型
3. **批量大小 1** 适用于有限 VRAM
4. **分块 VAE** 适用于高分辨率图像
5. **禁用预览** 用于更快生成

## GPU 要求

| 模型                | 最低 VRAM | 推荐 VRAM | 最低 RAM |
| ----------------- | ------- | ------- | ------ |
| SD 1.5            | 4GB     | 8GB     | 16GB   |
| SDXL              | 8GB     | 12GB    | 16GB   |
| SDXL + ControlNet | 10GB    | 16GB    | 16GB   |
| FLUX              | 16GB    | 24GB    | 32GB   |

## GPU 预设

### RTX 3060 12GB（预算型）

```bash
# 以优化参数启动
python main.py --lowvram --force-fp16

# 推荐设置：
# - SDXL：768x768，批量 1
# - SD 1.5：512x512，批量 4
# - 使用 VAE 分块
# - 20-30 步
```

**最适合：** SD 1.5、SDXL（有限制）

### RTX 3090 24GB（最佳）

```bash
# 标准启动
python main.py --force-fp16

# 推荐设置：
# - SDXL：1024x1024，批量 2
# - FLUX schnell：1024x1024，批量 1
# - ControlNet + SDXL 效果很好
# - 30-50 步
```

**最适合：** SDXL、ControlNet 工作流、中等 FLUX

### RTX 4090 24GB（性能型）

```bash
# 全速启动
python main.py

# 推荐设置：
# - SDXL：1024x1024，批量 4
# - FLUX dev：1024x1024，批量 1-2
# - 带有多个 ControlNet 的复杂工作流
# - 50+ 步以保证质量
```

**最适合：** FLUX、复杂工作流、批量生成

### A100 40GB/80GB（生产型）

```bash
# 最大性能
python main.py --highvram

# 推荐设置：
# - SDXL：1024x1024，批量 8+
# - FLUX：1024x1024，批量 2-4
# - 同时加载多个模型
# - 高分辨率输出（2048x2048）
```

**最适合：** 生产工作负载、FLUX、高分辨率生成

## 成本估算

CLORE.AI 市场的典型费率：

| GPU      | 显存   | 价格/天       | SDXL 速度  |
| -------- | ---- | ---------- | -------- |
| RTX 3060 | 12GB | $0.15–0.30 | \~15 秒/图 |
| RTX 3090 | 24GB | $0.30–1.00 | \~8 秒/图  |
| RTX 4090 | 24GB | $0.50–2.00 | \~4 秒/图  |
| A100     | 40GB | $1.50–3.00 | \~3 秒/图  |

*价格为美元/天。费率因提供商而异——请查看* [*CLORE.AI 市场*](https://clore.ai/marketplace) *以获取当前费率。*

## 故障排查

### 长时间出现 HTTP 502

1. **检查 RAM：** 服务器必须有 16GB+ RAM
2. **检查 VRAM：** SDXL 需要 8GB+，FLUX 需要 16GB+
3. **依赖项下载中：** 首次运行需要 5-10 分钟
4. **模型下载中：** 大型模型需要更长时间

### 内存不足

```bash
# 以低 VRAM 模式运行
python main.py --lowvram

# 或强制 fp16
python main.py --force-fp16
```

### 黑图像

* 检查 VAE 是否已加载
* 尝试不同的 VAE
* 减小图像尺寸

### 生成缓慢

* 启用 CUDA
* 使用 fp16 模型
* 减少步数（20-30 通常就足够）

## 工作流示例

在 ComfyUI 中导入这些 JSON 工作流：

* [基础 txt2img](https://comfyworkflows.com)
* [SDXL + Refiner](https://comfyworkflows.com)
* [ControlNet Canny](https://comfyworkflows.com)
* [AnimateDiff 视频](https://comfyworkflows.com)

## 下一步

* [ControlNet 指南](/guides/guides_v2-zh/tu-xiang-chu-li/controlnet-advanced.md)
* [Real-ESRGAN 超分辨率放大](/guides/guides_v2-zh/tu-xiang-chu-li/real-esrgan-upscaling.md)
* [Kohya 训练](/guides/guides_v2-zh/xun-lian/kohya-training.md) - 训练自定义 LoRA
* [Fooocus](/guides/guides_v2-zh/tu-xiang-sheng-cheng/fooocus-simple-sd.md) - 更简单的替代方案


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/comfyui.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.