| 退出（Ctrl+C），然后使用以下方式重新启动 `codex --oss --profile unsloth_api`。自定义提供方会跳过这一步 |
| 工具调用不可靠 | 需要自我修复回退 | Unsloth 的 [自我修复工具调用](file:///1382377/new/studio/#execute-code--heal-tool-calling) 默认已启用 |
| WSL： `连接被拒绝` 到 `localhost` | WSL 网络命名空间 | 在其中使用 Windows 主机 IP `base_url`，或者启用 WSL2 镜像网络 |
## 🦙 Llama.cpp 教程
我们也可以直接使用 `llama.cpp` 。我们需要部署 `llama-server` 这是一个开源框架，可在 Mac、Linux 和 Windows 设备上高效运行并提供 LLM 服务。模型将部署在 **8001 端口** ，所有智能体工具调用都将通过这个单一的 OpenAI 兼容端点路由。
{% hint style="info" %}
llama.cpp 端点将位于 **8001 端口** 而不是 `8888` （Unsloth Studio 的默认值）。相应调整你的 Codex `base_url` 在……中相应地 `~/.codex/config.toml`.
{% endhint %}
{% stepper %}
{% step %}
#### **安装 llama.cpp**
我们需要安装 `llama.cpp` 以部署/提供本地 LLM，供 Codex 使用。我们遵循官方构建说明，以获得正确的 GPU 绑定和最佳性能。将 `-DGGML_CUDA=ON` 到 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想使用 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后照常继续——Metal 支持默认开启。
```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev git-all -y
git clone https://github.com/ggml-org/llama.cpp
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 %}
#### **下载并在本地使用模型**
通过以下方式下载模型： `hf` 命令行工具（`pip install huggingface_hub hf_transfer`）。我们使用 **UD-Q4\_K\_XL** 量化版本，以获得最佳的尺寸/精度平衡。你可以在我们的 [集合中找到所有 Unsloth GGUF 上传](file:///1382377/get-started/unsloth-model-catalog.md)。如果下载卡住，请参见 [https://hugging-face-hub-xet-debugging.md](https://hugging-face-hub-xet-debugging.md "mention").
```bash
hf download unsloth/gemma-4-26B-A4B-it-GGUF \\
--local-dir unsloth/gemma-4-26B-A4B-it-GGUF \\
--include "*UD-Q4_K_XL*"
```
{% hint style="info" %}
**想要视觉支持？** 添加 `--include "*mmproj-BF16*"` 以便同时拉取视觉投影器，然后传入 `--mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf` 到 `llama-server`。Codex 本身仅支持文本，因此这是可选的。
{% endhint %}
{% hint style="success" %}
我们使用了 `unsloth/gemma-4-26B-A4B-it-GGUF`，但你可以使用任何类似的 `unsloth/Qwen3.6-35B-A3B-GGUF` - 见 [Qwen3.6-35B-A3B](/docs/zh/mo-xing/qwen3.6.md).
{% endhint %}
{% endstep %}
{% step %}
#### **启动 Llama-server**
要为智能体工作负载部署 Gemma-4-26B-A4B，我们使用 `llama-server`。我们采用 Google 推荐的采样参数（`温度 1.0`, `top_p 0.95`, `top_k 64`）并启用 `--jinja` 以获得正确的工具调用支持。
在新的终端中运行此命令（可使用 `tmux` ，或者打开一个新终端）。下面的内容应该 **轻松适配 24GB GPU（RTX 4090）** ，约占 18GB。 `--fit on` 也会自动卸载，但如果你看到性能变差，请减少 `--ctx-size`.
```bash
./llama.cpp/llama-server \\
--model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \\
--alias "unsloth/gemma-4-26B-A4B" \\
--temp 1.0 \
--top-p 0.95 \
--top-k 64 \\
--port 8001 \\
--kv-unified \\
--cache-type-k q8_0 --cache-type-v q8_0 \\
--batch-size 4096 --ubatch-size 1024
```
{% hint style="info" %}
我们使用了 `--cache-type-k q8_0 --cache-type-v q8_0` 用于 KV 缓存量化以减少 VRAM 占用。如果你发现质量下降，请使用 `bf16` 代替（`--cache-type-k bf16 --cache-type-v bf16`），但 VRAM 会翻倍。
{% endhint %}
{% hint style="success" %}
**禁用思考** 可以提升智能体编程任务的性能。Gemma 4 通过聊天模板默认启用思考——要禁用它，请将以下标志添加到 llama-server 命令中：
**macOS / Linux / WSL：**
`--chat-template-kwargs '{"enable_thinking":false}'`
**Windows PowerShell：**
`--chat-template-kwargs "{\"enable_thinking\":false}"`
{% endhint %}
{% endstep %}
{% step %}
#### **将 Codex 指向 8001 端口**
编辑你的 `~/.codex/config.toml` ，使其使用 llama-server 端口：
{% code title="\~/.codex/config.toml" %}
```toml
[model_providers.llama_cpp]
name = "llama.cpp"
base_url = "http://localhost:8001/v1"
env_key = "LLAMA_CPP_API_KEY"
wire_api = "responses"
```
{% endcode %}
然后使用新的配置文件启动：
```bash
codex --oss llama_cpp
```
由于 llama-server 不需要真实密钥，你可以把认证令牌设置为任意值：
{% code title="macOS / Linux / WSL" %}
```bash
export LLAMA_CPP_API_KEY=sk-no-key-required
```
{% endcode %}
{% code title="Windows PowerShell" %}
```powershell
$env:LLAMA_CPP_API_KEY = "sk-no-key-required"
```
{% endcode %}
{% endstep %}
{% endstepper %}
---
# 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/ji-chu-zhi-shi/codex.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.
.png?alt=media&token=c59c7110-402c-4d21-96c5-cd96c921a184)
