> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Lemonade Server 远程访问 — AMD NPU 和 GPU

> 从任何地方访问你的 Lemonade Server API — 支持 AMD NPU、Vulkan、ROCm、CUDA。使用 Tokios 连接器设置安全的远程访问，5 分钟即可开始服务。

默认情况下，Lemonade Server 监听 `http://127.0.0.1:13305/v1` — 除非你扩大绑定范围或转发端口，否则无法从其他机器访问。Lemonade Server 没有为远程访问提供内置身份验证。让它保持在 localhost 上运行，并在旁边运行 Tokios 连接器：连接器向 `https://api.tokios.com` 拨出，你的工具、团队成员或代理可以从任何地方调用一个经过身份验证的端点。

> [!NOTE]
>
> **最后验证：2026-10-14。** Lemonade Server 正在积极开发中 — 请访问 [lemonade-server.ai](https://lemonade-server.ai/) 获取最新版本。

> [!TIP]
>
> **AMD NPU 支持。** Lemonade Server 是唯一支持在 AMD Ryzen AI NPU（Ryzen AI 300/400 系列）上加速推理的本地 LLM 服务器。它还能自动检测 Vulkan、ROCm、CUDA 和 Metal 后端，因此无需手动配置即可在 AMD、NVIDIA 和 Apple Silicon 硬件上运行。

## Lemonade Server 是什么

Lemonade Server 是由 AMD 支持的开源本地 LLM 服务器。它在 `http://localhost:13305/v1` 提供 OpenAI 兼容的 API，并支持多种模型格式（GGUF、ONNX、FLM）和多种后端：

* **AMD Ryzen 7000/8000/200 系列** — 通过 Vulkan 实现 GPU 加速（llama.cpp 后端）
* **AMD Ryzen AI MAX+（Strix Halo）** — ROCm 配合 vLLM 或 llama.cpp
* **AMD Ryzen AI 300/400 系列** — 通过 ONNX Runtime GenAI 实现 NPU 加速（NPU+iGPU 混合执行）
* **NVIDIA GPU** — CUDA 加速
* **Apple Silicon** — Metal 后端

Lemonade Server 会自动检测你的硬件并选择最佳后端。你也可以根据需要手动覆盖后端选择。

> **为什么不直接把 Lemonade Server 绑定到 0.0.0.0？**
>
> 将 Lemonade Server 绑定到所有接口（`0.0.0.0`）可以让你的网络中的设备访问它，但 Lemonade Server 没有为远程调用者提供内置身份验证 — 任何能访问端口 `13305` 的人都可以调用 API。如果你的 ISP 使用 CGNAT，你一开始就没有稳定的公网 IP 可以转发。Tokios 添加了受限的 `sk-tok-…` API 密钥，无需打开入站端口。

> **为什么不使用 Tailscale 或 Cloudflare Tunnel？**
>
> Tailscale 很好地解决了个人访问问题 — 你自己的设备加入一个私有网格网络，可以安全地互相访问。但问题在于超出个人使用的场景：需要调用你模型的团队成员或 SaaS 客户端必须先加入你的 tailnet，这不适合公开 API 密钥的模式。Cloudflare Tunnel 通过 Cloudflare 的边缘网络路由流量，无需入站端口，但默认情况下 Cloudflare 会缓冲响应而不是流式传输，除非响应带有 `text/event-stream` 内容类型标头，而且代理请求受 Cloudflare 的代理超时限制（免费套餐约 100 秒）— 长时间生成可能会在流式传输中途被截断。

> [!NOTE]
>
> 这并不是在批评这些工具 — 它们解决的是不同的问题（设备网格网络、边缘代理）。Tokios 是专门为一个问题而构建的：将本地模型端点变成可以从任何地方调用的经过身份验证的 API。

## 前提条件

开始之前，请确保你具备以下条件：

* **已安装 Lemonade Server** — 参见下面的[如何安装 Lemonade Server](#how-to-install-lemonade-server)以下
* **已下载模型** — 使用 `lemonade pull <model>` 下载模型
* **Tokios 连接器** — 你将在设置过程中安装

## 如何安装 Lemonade Server

Lemonade Server 提供 Windows、Linux、macOS 和 Docker 的安装程序。从 v10.1 起，CLI 命令为 `lemonade`（旧的 `lemonade-server` CLI 已弃用）。

```powershell Windows (MSI) theme={"theme":{"light":"github-light","dark":"css-variables"}}
Download the MSI installer from the [Lemonade Server releases page](https://github.com/lemonade-sdk/lemonade/releases) and run it. The `lemond` service auto-starts on install.
```

```bash Linux (Snap) theme={"theme":{"light":"github-light","dark":"css-variables"}}
sudo snap install lemonade-server
```

```bash Linux (APT, Ubuntu/Debian) theme={"theme":{"light":"github-light","dark":"css-variables"}}
sudo apt update
sudo apt install lemonade-server
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
Download the macOS installer from the [Lemonade Server releases page](https://github.com/lemonade-sdk/lemonade/releases).
```

```bash Docker theme={"theme":{"light":"github-light","dark":"css-variables"}}
docker run -p 13305:13305 lemonade-sdk/lemonade-server
```

安装后，验证 Lemonade Server 正在运行：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
lemonade status
```

你应该能看到服务器状态和检测到的后端（Vulkan、ROCm、CUDA、Metal 或 NPU）。

## 如何使用 Lemonade Server 服务模型

只需 2 个命令即可下载并服务模型：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Download a model
lemonade pull Qwen3-0.6B-GGUF

# Serve the model
lemonade run Qwen3-0.6B-GGUF
```

Lemonade Server 会自动检测你的硬件并选择最佳后端。模型现在在 `http://localhost:13305/v1` 上提供服务。

> [!TIP]
>
> **AMD Ryzen AI 上的 NPU 加速。** 如果你拥有 AMD Ryzen AI 300/400 系列处理器，Lemonade Server 可以使用 NPU 进行推理。拉取一个针对 NPU 执行优化的 ONNX 模型：
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> lemonade pull Llama-3.2-1B-Instruct-NPU
> lemonade run Llama-3.2-1B-Instruct-NPU
> ```
>
> NPU 模型使用 NPU+iGPU 混合执行，通过 `-NPU` 后缀标识。

### Lemonade Server 常用 CLI 命令

| 命令 | 说明 |
| - | - |
| `lemonade pull <model>` | 下载模型 |
| `lemonade run <model>` | 服务模型 |
| `lemonade run <model> --ctx-size 8192` | 使用自定义上下文大小服务 |
| `lemonade list` | 列出可用模型 |
| `lemonade list --downloaded` | 列出已下载模型 |
| `lemonade status` | 检查服务器状态和检测到的后端 |
| `lemonade status --json` | 以 JSON 格式检查状态 |
| `lemonade bench <model>` | 对模型进行基准测试 |

## 仅出站方式

**1. 像往常一样在本地运行 Lemonade Server**

让 Lemonade Server 保持在 `127.0.0.1` — 不要绑定到回送地址之外。拉取并运行你的模型：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
lemonade pull Qwen3-0.6B-GGUF
lemonade run Qwen3-0.6B-GGUF
```

让它继续监听默认的 `http://127.0.0.1:13305`。

**2. 配对 Tokios 连接器**

在 [tokios.com/console](https://tokios.com/console) 登录，打开 **Setup** 标签页，然后点击 **Start pairing**。Tokios 会显示一个一次性的**配对码**，如 `TKS-XXXX-XXXX`，有效期约 15 分钟。

在运行 Lemonade Server 的机器上，运行适合你操作系统的一键安装命令：

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'
```

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX
```

```bash Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX
```

已经安装了 `tokios-connector`？直接传入配对码：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
tokios-connector TKS-XXXX-XXXX
```

回到控制台，**approve**该设备（位于 **Setup** 或 **Connectors** 标签页）。连接器的令牌在批准后通过隧道传递 — 你无需在屏幕上看到它或将其粘贴到文件中。

**3. 将连接器指向 Lemonade Server 的 /v1 API**

Lemonade Server 在 `/v1` 提供 OpenAI 兼容的接口，这正是 Tokios 通信的目标。对于基本的单模型路径，控制台的设置向导会自动使用 `http://127.0.0.1:13305/v1` 作为上游。如果你通过 `tokios-connector.json` 配置文件服务多个模型，请显式设置上游 `BaseUrl`：

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "Upstream": {
    "BaseUrl": "http://127.0.0.1:13305/v1"
  }
}
```

参见 [Connector config](/zh/reference/connector-config.md) 了解完整的多模型文件格式。

**4. 注册部署**

在 [Models](https://tokios.com/console/models) 标签页中，注册 Lemonade Server 模型并选择一个**公共名称** — 例如 `qwen3-tunnel`。客户端在 `model` 字段中发送的是这个公共名称，而不是 Lemonade 的本地模型 ID。

**5. 创建 API 密钥**

在 [Keys](https://tokios.com/console/keys) 标签页中，点击 **Create key**。你可以选择使用模型名称模式（逗号分隔的通配符，`*` 表示全部）将密钥限定到特定部署。立即复制 `sk-tok-…` 密钥 — 它仅显示一次。

## 从任何地方使用

有了部署名称和 API 密钥后，任何兼容 OpenAI 或 Anthropic 的客户端都可以访问你的 Lemonade Server 模型 — 无论是从另一台机器、团队成员的笔记本电脑还是托管代理。

```bash curl theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tunnel",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

```python Python (OpenAI SDK) theme={"theme":{"light":"github-light","dark":"css-variables"}}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokios.com/v1",
    api_key="sk-tok-YOUR_KEY",
)

response = client.chat.completions.create(
    model="qwen3-tunnel",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in response:
    print(chunk.choices[0].delta.content or "", end="")
```

```bash Claude Code theme={"theme":{"light":"github-light","dark":"css-variables"}}
export ANTHROPIC_BASE_URL=https://api.tokios.com
export ANTHROPIC_API_KEY=sk-tok-YOUR_KEY
claude --model qwen3-tunnel
```

> [!TIP]
>
> 该 `model` 字段始终是你注册的**部署**名称（上例中的 `qwen3-tunnel`），而不是 Lemonade 的本地模型 ID。参见 [使用 Claude Code](/zh/guides/claude-code.md) 了解如何在会话之间持久化环境变量。

## AMD NPU 支持是什么

AMD Ryzen AI 300/400 系列处理器包含一个专用的神经处理单元（NPU），用于 AI 工作负载。Lemonade Server 是唯一支持使用 NPU+iGPU 混合执行在 AMD NPU 上加速推理的本地 LLM 服务器。

### NPU 加速的工作原理

* **模型格式**：NPU 优化模型使用 ONNX 格式（通过 `-NPU` 后缀标识，例如 `Llama-3.2-1B-Instruct-NPU`）
* **执行方式**：Lemonade Server 使用 OnnxRuntime GenAI 在 NPU 和 iGPU 之间分配推理任务
* **后端**：NPU 后端是自动的 — Lemonade Server 检测你的 Ryzen AI 处理器，当你运行 NPU 优化模型时选择 NPU 执行
* **性能**：NPU 加速将工作从 CPU 和 GPU 卸载，降低功耗并释放资源供其他任务使用

### 哪些 AMD 处理器支持 NPU 推理

| 处理器系列 | NPU 支持 | 后端 |
| - | - | - |
| AMD Ryzen AI 300 系列（Strix Point） | 是 | NPU（通过 ONNX） |
| AMD Ryzen AI 400 系列 | 是 | NPU（通过 ONNX） |
| AMD Ryzen AI MAX+（Strix Halo） | 无 NPU，但有强大的 iGPU | ROCm/vLLM 或 Vulkan |
| AMD Ryzen 7000/8000 系列 | 无 NPU | Vulkan（llama.cpp） |

> [!NOTE]
>
> NPU 支持需要 AMD Ryzen AI Software 驱动。Lemonade Server 捆绑了必要的运行时，但请确保你的系统已安装最新的 AMD Adrenalin 驱动。

## Lemonade Server 与其他后端的对比

Lemonade Server 是 Tokios 支持的多种后端之一。以下是它的对比情况：

| 特性 | Lemonade Server | Ollama | llama.cpp | vLLM |
| - | - | - | - | - |
| **AMD NPU 支持** | 是（Ryzen AI 300/400） | 否 | 否 | 否 |
| **自动检测后端** | 是（Vulkan/ROCm/CUDA/Metal） | 手动 | 手动 | 手动 |
| **安装复杂度** | 低（安装程序） | 低（一条命令） | 中（编译） | 高（Python GPU 服务器） |
| **模型格式** | GGUF、ONNX、FLM | GGUF | GGUF | Hugging Face |
| **最适合** | AMD 硬件；跨平台 | 新手；最快上手 | 动手派 GGUF 服务 | 高吞吐量 GPU 服务 |

> [!TIP]
>
> 如果你拥有 AMD 硬件（尤其是带 NPU 的 Ryzen AI）或想要一个自动检测后端的跨平台服务器，Lemonade Server 是一个很好的选择。如果你只想在任何硬件上最快上手，[Ollama](/zh/guides/ollama-remote-access.md) 仍然是最简单的。

## 常见问题

> **Lemonade Server 使用哪个端口？**
>
> Lemonade Server 默认监听端口 **13305**，绑定到 `127.0.0.1`（仅限 localhost）。OpenAI 兼容的 API 位于 `http://localhost:13305/v1`。你可以使用 `lemonade status` 或 `curl http://localhost:13305/v1/models` 验证 Lemonade Server 是否正在运行。

> **如何知道 Lemonade Server 使用的是哪个后端？**
>
> 运行 `lemonade status` 查看检测到的后端（Vulkan、ROCm、CUDA、Metal 或 NPU）。Lemonade Server 会自动检测你的硬件并选择最佳后端。你也可以使用 `lemonade status --json` 获取机器可读的输出。

> **Lemonade Server 支持 AMD NPU 吗？**
>
> 支持。Lemonade Server 是唯一支持在 AMD Ryzen AI 300/400 系列 NPU 上加速推理的本地 LLM 服务器。使用 `lemonade pull <model>-NPU` 拉取 NPU 优化模型，使用 `lemonade run <model>-NPU` 运行它。NPU 后端通过 OnnxRuntime GenAI 使用 NPU+iGPU 混合执行。

> **Lemonade Server 可以配合 NVIDIA GPU 使用吗？**
>
> 可以。Lemonade Server 会自动检测 NVIDIA GPU 并使用 CUDA 后端。它支持任何支持 Vulkan、ROCm、CUDA 或 Metal 的硬件 — AMD、NVIDIA 和 Apple Silicon 均受支持。

> **如何将 Lemonade Server 暴露给网络？**
>
> 不要直接暴露 Lemonade Server — 请使用 Tokios。Tokios 添加经过身份验证的远程访问，无需打开入站端口。参见[上面的设置步骤](#the-outbound-only-way)了解完整流程。

> **流式传输能用吗？**
>
> 可以。设置 `"stream": true`，Tokios 会返回标准的服务器发送事件（SSE），采用 OpenAI 或 Anthropic 格式，具体取决于你调用的 API 接口。

> **我可以在不直接暴露 Lemonade Server 的情况下与团队成员共享访问权限吗？**
>
> 可以。为每个团队成员创建单独的 `sk-tok-…` 密钥（在 [Keys](https://tokios.com/console/keys) 标签页中），并将每个密钥限定到他们需要的部署。撤销密钥会立即停止其身份验证，因此你可以在不触及 Lemonade Server 或连接器的情况下切断访问权限。

> **我可以暴露超过 1 个 Lemonade Server 模型吗？**
>
> 可以。在 [Models](https://tokios.com/console/models) 标签页中注册额外的部署，或使用 `tokios-connector.json` 配置文件为单个连接器定义多个上游和路由。参见 [Connector config](/zh/reference/connector-config.md)。

> **如何更新 Lemonade Server？**
>
> 在 Linux 上，运行 `sudo apt update && sudo apt upgrade lemonade-server`（APT）或 `sudo snap refresh lemonade-server`（Snap）。在 Windows 上，从[发布页面](https://github.com/lemonade-sdk/lemonade/releases)下载最新的 MSI 安装程序。

> **NPU 支持哪些模型架构？**
>
> NPU 支持针对 ONNX 执行优化的特定模型架构。运行 `lemonade list` 查看可用的 NPU 模型（通过 `-NPU` 后缀标识）。并非所有模型都兼容 NPU — GGUF 模型改为在 GPU/CPU 后端上运行。参见 [Lemonade FAQ](https://lemonade-server.ai/docs/guide/faq/) 获取 NPU 支持的架构完整列表。

## 你的模型永远不会离开你的机器 — 你的端点在任何地方都能工作

Lemonade Server 继续做它现在做的事情，在 localhost 上，没有入站端口，没有暴露的 API。连接器只向外拨号。此后的一切 — 身份验证、路由、流式传输 — 都是一个端点，你可以从任何你选择给予密钥的机器、团队成员或代理调用。

> **[快速入门](/zh/quickstart.md)**
>
> 配对连接器并端到端注册你的第一个模型。

> **[API 密钥](/zh/setup/api-keys.md)**
>
> 为团队成员和代理创建、限定范围并轮换 `sk-tok-…` 密钥。

> **[Strix Halo 设置](/zh/use-cases/strix-halo.md)**
>
> 将你的 AMD Strix Halo 主机变成使用 Lemonade Server 的模型端点。

> **[支持的后端](/zh/setup/supported-backends.md)**
>
> 查看 Tokios 支持的所有后端 — Ollama、llama.cpp、vLLM、LM Studio 等。

## 资料来源

* [Lemonade SDK GitHub 仓库](https://github.com/lemonade-sdk/lemonade)
* [Lemonade Server 官方文档](https://lemonade-server.ai/docs/guide/faq/)
* [AMD：通过 Lemonade Server 在 Ryzen AI 上释放 LLM 应用浪潮](https://www.amd.com/en/developer/resources/technical-articles/unlocking-a-wave-of-llm-apps-on-ryzen-ai-through-lemonade-server.html)
* [Lemonade 入门指南 | AMD AI Playbooks](https://developer.amd.com/playbooks/lemonade-getting-started/)
* [Lemonade Server CLI 文档](https://lemonade-server.ai/docs/guide/cli/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.