> 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 - 如何在本地运行

在你的设备上本地运行并微调 Nemotron-3-Nano-Omni-30B-A3B！

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

使用 **256K 上下文**时，Nemotron 3 Nano Omni 是 **同尺寸中最强的 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-bit 版本需要约 25GB RAM。8-bit 需要 36GB。对于这些指南，我们将使用 `UD-Q4-K-XL` 这在体积和准确性之间取得了良好平衡。

<a href="/docs/zh/mo-xing/nemotron-3-nano-omni.md#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 的全新网页界面。使用 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) 参数调优（温度、top-p 等）
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度快 2 倍，VRAM 占用减少 70%
  {% endcolumn %}

{% column %}

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FFeQ0UUlnjXkDdqhcWglh%2Fskinny%20studio%20chat.png?alt=media&amp;token=c2ee045f-c243-4024-a8e4-bb4dbe7bae79" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fd1yMMNa65Ccz50Ke0E7r%2FScreenshot%202026-03-17%20at%2012.32.38%E2%80%AFAM.png?alt=media&amp;token=9369cfe7-35b1-4955-b8cb-42f7ecb43780" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FQUTU2gI4DNuscVEuiT8f%2FScreenshot%202026-03-20%20at%201.28.50%E2%80%AFAM.png?alt=media&amp;token=74d5fd9e-a229-4ddc-a96d-abe68e1ca6a3" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FXPQGEEr1YoKofrTatAKK%2Ftoolcallingif.gif?alt=media&amp;token=25d68698-fb13-4c46-99b2-d39fb025df08" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-9bf7ec93680f889d7602e5f56a8d677d6a58ae6a%2Funsloth%20made%20with%20love.png?alt=media" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-4b30cc86b2c75edf95ee1ec6fe0c51fb30afd6c0%2F8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg?alt=media" 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*" # 对于 Dynamic 2 位使用 "*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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FiocWqkHECR9o9Fufepqs%2Fimage.png?alt=media&amp;token=f9ec7bc5-2d80-4fff-94ef-0aaf9c80a095" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

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

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHn6j4OoFDiIth4sBDGBF%2Fimage.png?alt=media&amp;token=b4d1e448-73e9-4942-b465-ee9b80361447" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FvwqETRkGCwWUgpYqoEnZ%2Fimage.png?alt=media&amp;token=39e0fd0f-d7c2-4689-b3b1-3f8003a94dad" alt="" width="563"><figcaption></figcaption></figure>
{% endstep %}

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

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnlL5IizsVPiO655YHkYx%2Fimage.png?alt=media&amp;token=e414e213-e64d-4167-a5ae-7f52fa19b635" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F7Y9vyJDtdxkMlYMcS9PT%2Fimage.png?alt=media&amp;token=a1b46fb5-ed87-4f22-b035-de935a6ac7d3" 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="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FhPQNQGHicFdRXkThKapE%2Fimage.png?alt=media&amp;token=1a77fc30-0afb-4e37-b4b0-9d38bdf7decd" alt=""><figcaption></figcaption></figure>

### 🦥 微调 Nemotron 3 Nano Omni

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

对于仅文本和 notebook，你可以从现有的 [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 是同尺寸中最强的 omni 模型。它也是最高效、具有领先准确率的开源多模态模型。该模型在所有基准测试上都优于 Qwen3-Omni-30B-A3B。

<div data-with-frame="true"><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FVeilBuCszSJr4yoJDaGm%2Funnamed.png?alt=media&amp;token=5fe8205c-6f2b-40c3-a0e2-ef254a357d2b" 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 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/zh/mo-xing/nemotron-3-nano-omni.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.