> 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/zh/mo-xing/nemotron-3-nano-omni.md).

# NVIDIA Nemotron 3 Nano Omni - 如何本地运行

NVIDIA Nemotron-3-Nano-Omni-30B-A3B 是一个开源的 300 亿参数、30 亿激活的混合推理 MoE 模型，专为多模态智能体工作负载而构建，包括 **音频**, **视频**、文本、图像和文档作为输入，并输出文本。该模型运行在 **25GB RAM** 用于 4 位，8 位为 36GB。

具有 **256K 上下文**，Nemotron 3 Nano Omni 是 **同等规模中最强的全模态** 模型，也是效率最高的开源多模态模型。我们与 NVIDIA 合作提供了首日支持！\
**GGUF:** [Nemotron-3-Nano-Omni-30B-A3B-Reasoning](https://huggingface.co/unsloth/Nemotron-3-Nano-30B-A3B-GGUF)

### ⚙️ 使用指南

NVIDIA 建议以下推理设置：

{% columns %}
{% column %}
**思考模式：**

* `temperature = 0.6`
* `top_p = 0.95`
  {% endcolumn %}

{% column %}
**指令模式：**

* `temperature = 0.2`
  {% endcolumn %}
  {% endcolumns %}

### 运行 Nemotron-3-Nano-Omni

根据你的使用场景，你需要使用 [不同设置](#usage-guide)。有些 GGUF 文件最终大小相近，因为模型架构（例如 [gpt-oss](/docs/zh/mo-xing/gpt-oss-how-to-run-and-fine-tune.md)）的维度不能被 128 整除，因此部分权重无法量化到更低比特。 **GGUF:** [Nemotron-3-Nano-Omni-30B-A3B-Reasoning](https://huggingface.co/unsloth/Nemotron-3-Nano-30B-A3B-GGUF)

该模型的 4 位版本需要约 25GB RAM。8 位需要 36GB。在本指南中，我们将使用 `UD-Q4-K-XL` 这是大小和准确性之间的良好平衡。

<a href="/pages/31f07ee6a66a73019ccc7bc333592f8522540f7b#unsloth-studio-guide" class="button primary">在 Unsloth Studio 中运行</a><a href="/pages/31f07ee6a66a73019ccc7bc333592f8522540f7b#llama.cpp-tutorial" class="button secondary">在 llama.cpp 中运行</a>

{% hint style="warning" %}
目前没有任何多模态/视觉 GGUF 可以在 **Ollama** 中工作，因为它们使用单独的 `mmproj` 视觉文件。请使用兼容 llama.cpp 的后端。

不要使用 **CUDA 13.2** ，否则你可能会得到乱码输出。NVIDIA 正在修复。
{% endhint %}

### 🦥 Unsloth Studio 指南

在本教程中，我们将使用 [Unsloth Studio](/docs/zh/xin/studio.md)，这是我们用于运行和训练 LLM 的新 Web UI。使用 Unsloth Studio，你可以在本地运行模型并输入 **音频**、图像和文本，适用于 **Mac、Windows**和 Linux，并且：

{% columns %}
{% column %}

* 搜索、下载、 [运行 GGUF](/docs/zh/xin/studio.md#run-models-locally) 和 safetensor 模型
* **对比** 模型 **并排**
* [**自我修复** 工具调用](/docs/zh/xin/studio.md#execute-code--heal-tool-calling) + **网页搜索**
* [**代码执行**](/docs/zh/xin/studio.md#run-models-locally) （Python、Bash）
* [自动推理](https://unsloth.ai/docs/desktop#feature-deep-dive) 参数调优（temp、top-p 等）
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度快 2 倍，VRAM 占用减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="/files/5af4df407c8134f1ff75a4d7535569361c049e51" alt=""><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% stepper %}
{% step %}

#### 安装 Unsloth

**MacOS、Linux、WSL：**

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

**Windows PowerShell：**

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

{% endstep %}

{% step %}

#### 设置 Unsloth Studio（一次性）

设置会自动安装 Node.js（通过 nvm）、构建前端、安装所有 Python 依赖，并构建启用 CUDA 支持的 llama.cpp。

{% hint style="info" %}
**WSL 用户：** 系统会提示你输入 `sudo` 密码，以安装构建依赖项（`cmake`, `git`, `libcurl4-openssl-dev`).
{% endhint %}
{% endstep %}

{% step %}

#### 启动 Unsloth

**MacOS、Linux、WSL：**

```bash
source unsloth_studio/bin/activate
unsloth studio -H 0.0.0.0 -p 8888
```

**Windows Powershell：**

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

<div data-with-frame="true"><figure><img src="/files/7fd4b2ed7fb55df6d31b4dd1ce1181d57613709b" alt="" width="375"><figcaption></figcaption></figure></div>

然后打开 `http://127.0.0.1:8888` 在你的浏览器中。
{% endstep %}

{% step %}

#### 搜索并下载 NVIDIA-Nemotron-3-Nano-30B-A3B-Omni

首次启动时，你需要创建一个密码来保护你的账户，并在之后重新登录。然后前往 [Unsloth Chat](/docs/zh/xin/studio/chat.md) 选项卡中，在搜索栏里搜索 Nemotron-3-Nano-Omni，并下载你想要的模型和量化版本。

<div data-with-frame="true"><figure><img src="/files/d25d2eb333ee1d420f0ef614baf4e78ae035975a" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### 运行 Nemotron-3-Nano-30B-A3B-Omni

在使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍然可以手动更改。你也可以编辑上下文长度、聊天模板和其他设置。

更多信息请查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).

<div data-with-frame="true"><figure><img src="/files/6273055e6bbde016134838582519f00de2201635" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

### 🦙 Llama.cpp 教程：

在 llama.cpp 中运行的说明（注意我们将使用 4-bit，以适配大多数设备）：

{% stepper %}
{% step %}
获取最新的 `llama.cpp` 在 [GitHub 这里](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明操作。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想进行 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后按常规继续——Metal 支持默认开启。

{% code overflow="wrap" %}

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=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
```

{% endcode %}
{% endstep %}

{% step %}
**我们先获取一张图片！** 你也可以上传图片。我们将使用 <https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png>，这只是我们的小徽标，用来展示如何使用 Unsloth 制作微调模型：

{% code overflow="wrap" %}

```bash
wget https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png -O unsloth.png
```

{% endcode %}

<figure><img src="/files/99e6294684309cf45754d5010bc1bff5c7da4548" alt="" width="188"><figcaption></figcaption></figure>

让我们获取第二张图片，地址是 <https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg>

{% code overflow="wrap" %}

```bash
wget https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg -O picture.png
```

{% endcode %}

<figure><img src="/files/dfadcc899fed5f74e2966aa94681fc7f2b43caa2" alt="" width="188"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
现在让我们手动下载模型。安装 pip install huggingface\_hub 后，可以通过下面的代码完成。如果下载卡住，请参阅： [Hugging Face Hub、XET 调试](/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md)

{% code overflow="wrap" %}

```bash
pip install huggingface_hub
hf download unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF \\
    --local-dir unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF \\
    --include "*mmproj-BF16*" \\
    --include "*UD-Q4_K_XL*" # 动态 2bit 请使用 "*UD-Q2_K_XL*"
```

{% endcode %}
{% endstep %}

{% step %}
然后以对话模式运行模型：

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-cli \
    --model unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF/mmproj-BF16.gguf \\
    --temp 0.6 \\
    --top-p 0.95 \\
    --min-p 0.01
```

{% endcode %}
{% endstep %}

{% step %}
然后你会看到如下内容：

<figure><img src="/files/aa11ded6507257cddf37f2497ad591403787b93d" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
然后使用 `/image` 来加载两张图片并询问“这是什么图片”：

<figure><img src="/files/9002f042641fae85a4309630f7dddd6db39c0710" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="/files/b61454f64630b4a72a3770eec755cfe50eb20d49" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
对于树懒图片：

<figure><img src="/files/011802211997ecf8d7a0cd3c3e010bb994d33b35" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

#### llama-server 提供服务与部署

要在本地部署 Nemotron 3 Nano Omni，请使用 `llama-server`。在新的终端中，例如通过 `tmux`，部署模型：

```bash
./llama.cpp/llama-server \\
    -hf unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF:UD-Q4_K_XL \\
    --alias "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning" \\
    --prio 3 \\
    --temp 0.6 \\
    --top-p 0.95 \\
    --port 8001
```

如果你手动下载了模型，请使用：

{% code overflow="wrap" %}

```bash
./llama.cpp/llama-server \\
    --model unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF/mmproj-BF16.gguf \\
    --alias "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning" \\
    --prio 3 \\
    --temp 0.6 \\
    --top-p 0.95 \\
    --port 8001
```

{% endcode %}

然后在新的终端中，在使用以下命令安装 OpenAI 客户端后 `pip install openai`:

```python
from openai import OpenAI
openai_client = OpenAI(
    base_url = "http://127.0.0.1:8001/v1",
    api_key = "sk-no-key-required",
)
completion = openai_client.chat.completions.create(
    model = "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning",
    messages = [
        {"role": "user", "content": "2+2 等于多少？"},
    ],
)
print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```

将显示类似如下内容：

<figure><img src="/files/fd629ac175b9ca8c3fd297e94702afcea6e34037" alt="" width="563"><figcaption></figcaption></figure>

#### 通过兼容 OpenAI 的服务器进行图像输入

让我们使用 `picture.png` 这就是树懒图片，类似于 [#llama.cpp-tutorial](#llama.cpp-tutorial "mention")

{% code expandable="true" %}

```python
from openai import OpenAI
import base64
import mimetypes
image_link = "picture.png"

def file_to_data_url(path: str) -> str:
    mime = mimetypes.guess_type(path)[0] or "application/octet-stream"
    with open(path, "rb") as f:
        data = base64.b64encode(f.read()).decode("utf-8")
    return f"data:{mime};base64,{data}"

openai_client = OpenAI(
    base_url = "http://127.0.0.1:8001/v1",
    api_key = "sk-no-key-required",
)

completion = openai_client.chat.completions.create(
    model = "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning",
    messages = [ {
        "role": "user",
        "content": [
            { "type": "text", "text": "这是什么图片？", },
            {
                "type": "image_url",
                "image_url": { "url": file_to_data_url(image_link), },
            },
        ],
    } ],
)
print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```

{% endcode %}

将显示类似如下内容：

<figure><img src="/files/662bf5f0102d6d53becb34fe4ab32802f63613d0" alt=""><figcaption></figcaption></figure>

### 🦥 微调 Nemotron 3 Nano Omni

Unsloth 支持整个 [Nemotron](/docs/zh/mo-xing/nemotron-3.md) 模型家族。Nemotron 3 Nano Omni 适用于多模态智能体数据集。你可以通过 Unsloth 训练音频、视觉或文本。 **视频输入** 目前不支持微调。

对于仅文本和笔记本场景，你可以从现有的 [Nemotron 3 Nano 微调流程](/docs/zh/mo-xing/nemotron-3.md#fine-tuning-nemotron-3-and-rl)。对于多模态适配器，请确保你的数据集包含你的智能体实际需要的模态：

* **计算机使用：** 截图、UI 状态、光标/上下文、预期的下一步操作
* **文档智能：** PDF、截图、图表、表格、结构化抽取目标
* **音频理解：** 音频片段、采样帧、摘要、时间戳、事件和后续问题
* **智能体循环：** 观察 → 推理 → 行动 → 验证示例

对于 Omni，不要盲目复用纯文本 VRAM 数值。多模态编码器、投影层权重、图像 token、音频片段和长上下文都会增加内存占用。请从较短上下文和较小批大小开始，然后再逐步扩展。

### 基准测试

Nemotron 3 Nano Omni 是其规模下最强的全模态模型。它也是效率最高、准确率领先的开源多模态模型。该模型在所有基准上都优于 Qwen3-Omni-30B-A3B。

<div data-with-frame="true"><figure><img src="/files/71bb321919b26ac48b2490a6ef167733fcebcfca" alt="" width="563"><figcaption></figcaption></figure></div>


---

# 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://unsloth.ai/docs/zh/mo-xing/nemotron-3-nano-omni.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.