> ## 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-.

# 从任何地方安全地使用 MLX-LM Server

> 从任何地方访问你在 Apple Silicon 上运行的 MLX-LM Server — 使用 Tokios 连接器和 API 密钥认证设置安全远程访问。5 分钟即可开始服务。

默认情况下，`mlx_lm.server` 监听 `http://127.0.0.1:8080/v1` — 除非你扩大绑定地址或转发端口，否则无法从其他机器访问。MLX-LM Server 没有内置认证：任何能到达端口 `8080` 的程序都可以无凭证地调用 API。让 MLX-LM Server 保持在 localhost 上运行，在其旁边运行 Tokios 连接器：连接器向 `https://api.tokios.com` 拨出连接，你的工具、团队成员或代理可以从任何地方调用一个经过认证的端点。

> [!NOTE]
>
> 最后验证时间：2026-10-14。MLX-LM Server 随 Apple ml-explore 团队发布的 [`mlx-lm`](https://github.com/ml-explore/mlx-lm) Python 包提供。本指南涵盖当前版本。

> [!TIP]
>
> **Apple Silicon 原生。** MLX-LM Server 是 Apple Silicon 的参考推理服务器。它使用 MLX 框架的统一内存架构和零拷贝数据路径 — 模型权重与 CPU 和 GPU 共享同一个内存池，因此无需单独管理 VRAM。在 M5 芯片上，Neural Accelerators 可实现高达 4x 的提示处理速度提升（对比 M4）。

## 什么是 Apple Silicon 原生推理

MLX-LM Server 与 Tokios 支持的其他后端不同：它仅运行在 Apple Silicon Mac（M1 及更新机型）上，并直接利用所有 Apple Silicon 芯片共有的统一内存架构。

| 特性 | MLX-LM Server | llama.cpp on Mac | vLLM |
| - | - | - | - |
| 硬件 | 仅限 Apple Silicon | 跨平台（CPU + GPU） | NVIDIA GPU（CUDA） |
| 内存模型 | 统一内存，零拷贝 | 通过 Metal 实现统一内存 | 独立 VRAM |
| Neural Accelerators（ANE） | 支持 — M5 自动启用 | 不支持 | 不支持 |
| 安装 | `pip install mlx-lm` | 从源码构建或预编译二进制文件 | `pip install vllm` + CUDA |
| 量化 | 4-bit、8-bit、BF16 | GGUF（Q2\_K 至 Q8\_0） | AWQ、GPTQ、FP16、BF16 |
| M5 上的提示处理 | 高达 4x（对比 M4） | 基准 | N/A |

由于 MLX 使用统一内存，配备 192 GB 内存的 Mac Studio 可以全精度服务 70B 模型，无需其他平台所需的多 GPU 配置。没有 VRAM 边界 — 模型、KV 缓存和工作内存共享同一个内存池。

## MLX-LM Server 的认证默认关闭

`mlx_lm.server` 在端口 `8080` 上启动一个兼容 OpenAI 的 HTTP 服务器。运行它后，任何能到达该端口的人都可以发送请求 — 无需凭证：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
mlx_lm.server --model mlx-community/Qwen-3.5-4B-8bit
```

MLX-LM Server 不附带认证层。其[自身文档](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/SERVER.md)指出，不建议在没有反向代理的生产环境中使用该服务器。这对仅本地使用没有问题，但这意味着通过 `--host 0.0.0.0`、端口转发或隧道将端口暴露到环回地址之外，会让任何能到达该端口的人获得无认证的 API 访问权限。

> [!NOTE]
>
> 这并不是对 MLX-LM Server 的批评 — 它是一个轻量级的 Apple Silicon 原生推理服务器，将认证交给外部代理可以保持服务器简洁。Tokios 专为另一个问题而构建：将本地端点转变为可从任何地方调用的认证 API，无需开放入站端口或手动配置 TLS。

## 仅出站方式

**1. Install MLX-LM and start the server locally**

MLX-LM Server 需要一台 Apple Silicon Mac（M1 或更新机型），运行 macOS 14.0（Sonoma）或更高版本。安装该包并启动服务器：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
pip install mlx-lm
mlx_lm.server --model mlx-community/Qwen-3.5-4B-8bit
```

服务器在首次使用时从 [mlx-community](https://huggingface.co/mlx-community) 下载模型，并监听 `http://127.0.0.1:8080`。保持默认的 `127.0.0.1` — 不要传递 `--host 0.0.0.0`。

> [!TIP]
>
> **选择量化。** mlx-community 上的模型提供 4-bit（默认，最小）、8-bit 和 BF16（全精度）变体。70B 模型在 4-bit 下大约需要 35 GB 统一内存；8-bit 下大约 70 GB；BF16 下大约 140 GB。选择适合你 Mac 内存的量化方案。

**2. Pair the Tokios connector**

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

在运行 MLX-LM Server 的 Mac 上，运行 macOS 一键安装命令：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/macos | 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. Point the connector at MLX-LM Server's /v1 API**

MLX-LM Server 已经使用 Tokios 所需的 OpenAI Chat Completions 接口。对于基本的单模型路径，控制台的 Setup 向导自动使用 `http://127.0.0.1:8080/v1` 作为上游。如果你通过 `tokios-connector.json` 配置服务多个模型，请显式设置上游 `BaseUrl`：

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

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

**4. Register a deployment**

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

**5. Create an API key**

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

## 从任何地方使用

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

```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": "mlx-qwen-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="mlx-qwen-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 mlx-qwen-tunnel
```

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

## 服务器配置参考

MLX-LM Server 提供多个用于调优推理的参数。以下是最常用的参数：

| 参数 | 默认值 | 用途 |
| - | - | - |
| `--model` | （必需） | HuggingFace 模型 ID 或本地路径 |
| `--host` | `127.0.0.1` | 绑定地址 — 对于 Tokios，保持 `127.0.0.1` 不变 |
| `--port` | `8080` | 监听端口 |
| `--adapter-path` | — | LoRA 适配器路径，用于服务微调模型 |
| `--max-tokens` | `512` | 每次生成的默认最大 token 数 |
| `--temp` | `0.0` | 采样温度 |
| `--top-p` | `1.0` | Top-p（核心）采样 |
| `--top-k` | `0` | Top-k 采样（0 = 禁用） |
| `--kv-bits` | — | KV 缓存量化位数（减少内存占用） |
| `--kv-group-size` | `64` | KV 缓存量化的分组大小 |
| `--prefill-step-size` | `2048` | 长上下文的预填充块大小 |
| `--draft-model` | — | 推测解码用的草稿模型 |
| `--num-draft-tokens` | `3` | 每步推测解码的草稿 token 数 |
| `--prompt-cache-size` | `10` | 缓存的提示数量 |
| `--decode-concurrency` | `32` | 最大并发解码操作数 |
| `--prompt-concurrency` | `8` | 最大并发提示操作数 |
| `--trust-remote-code` | `false` | 信任来自 HuggingFace 仓库的远程代码 |

服务器暴露以下端点：

| 端点 | 用途 |
| - | - |
| `/v1/chat/completions` | Chat Completions（兼容 OpenAI） |
| `/v1/completions` | Text Completions（兼容 OpenAI） |
| `/v1/models` | 列出已加载的模型 |
| `/health` | 健康检查 |

> [!TIP]
>
> **推测解码**可以将大型模型的生成速度提升 2-3x。传递 `--draft-model` 并使用同系列的较小模型 — 例如，使用 4B 模型作为 32B 模型的草稿。MLX-LM Server 并行验证草稿 token，仅重新计算不匹配的部分。

## 常见问题

> **What are the prerequisites for MLX-LM Server?**
>
> 你需要一台 Apple Silicon Mac（M1、M2、M3、M4 或 M5），运行 macOS 14.0（Sonoma）或更高版本，Python 3.9 或更高版本，以及 `pip` 或 `conda`。使用 `pip install mlx-lm` 安装。MLX 框架使用 Metal 进行 GPU 加速，使用统一内存存放模型权重 — 无需单独的 GPU 驱动或 CUDA 工具包。

> **How do I install MLX-LM Server?**
>
> 使用 `pip install mlx-lm`（或 `conda install -c conda-forge mlx-lm`）安装 Python 包。然后使用 `mlx_lm.server --model <model-id>` 启动服务器。模型在首次使用时从 HuggingFace 下载。[mlx-community](https://huggingface.co/mlx-community) 组织的模型已预转换为 MLX 格式，可直接使用。

> **What port does MLX-LM Server use?**
>
> MLX-LM Server 默认监听端口 **8080**，绑定到 `127.0.0.1`（仅限 localhost）。使用 `--port` 更改端口，使用 `--host` 更改绑定地址。对于 Tokios，请保持默认值 — 连接器通过 `http://127.0.0.1:8080/v1` 访问服务器。

> **Does MLX-LM Server support streaming?**
>
> 支持。在请求体中设置 `"stream": true`，服务器返回标准的服务器发送事件（SSE）。通过 Tokios，流式传输端到端工作 — 设置 `"stream": true`，Tokios 根据你调用的 API 接口返回 OpenAI 或 Anthropic 格式的 SSE。

> **Does MLX-LM Server support tool calling?**
>
> 支持。MLX-LM Server 支持结构化工具调用。使用支持带工具定义的聊天模板的模型 — 来自 [mlx-community](https://huggingface.co/mlx-community) 的模型（如 Qwen 3.5 和 Llama 3）包含必要的聊天模板。在请求的 OpenAI 兼容 `tools` 字段中传递工具定义。

> **Can I use LoRA adapters with MLX-LM Server?**
>
> 可以。传递 `--adapter-path` 指向包含 LoRA 适配器权重的目录。使用 `mlx_lm.lora`（包含在同一包中）微调适配器，然后服务带有适配器叠加的基础模型。将适配器注册为独立的 Tokios 部署，并指定独立的公共名称。

> **How does MLX-LM Server compare to llama.cpp on Apple Silicon?**
>
> 两者都使用 Apple Silicon 上的统一内存。MLX-LM Server 是 Apple 原生路径 — 直接使用 Metal GPU 加速，在 M5 芯片上利用 Neural Accelerators 可实现高达 4x 的提示处理加速。llama.cpp 是跨平台的，支持更广泛的量化格式（GGUF 变体）。在纯 Apple Silicon 性能方面，MLX-LM Server 在 M 系列芯片上与 llama.cpp 相当或略有优势。

> **Can I serve more than one model?**
>
> 可以。在不同端口上运行多个 `mlx_lm.server` 进程，或在 [Models](https://tokios.com/console/models) 标签页中注册额外的部署。使用 `tokios-connector.json` 配置文件为单个连接器定义多个上游和路由。参见 [Connector config](/zh/reference/connector-config.md) 了解完整的多模型文件格式。

> **Can I share access with teammates without exposing MLX-LM Server directly?**
>
> 可以。为每位团队成员创建独立的 `sk-tok-...` 密钥（在 [Keys](https://tokios.com/console/keys) 标签页中），并将每个密钥限定为他们所需的部署。撤销密钥会立即停止其认证，因此你可以在不接触 MLX-LM Server 或连接器的情况下切断访问权限。

> **What models work with MLX-LM Server?**
>
> HuggingFace 上任何已转换为 MLX 格式的模型。[mlx-community](https://huggingface.co/mlx-community) 维护着热门模型的预转换版本 — Llama、Qwen、Mistral、Gemma、Phi 等 — 提供 4-bit、8-bit 和 BF16 量化。你也可以使用 `mlx_lm.convert` 自行转换模型。

## 模型不离开你的机器 — 你的端点随处可用

MLX-LM Server 继续在 localhost 上运行，没有入站端口，没有暴露的 API。连接器仅向外拨出连接。此后的一切 — 认证、路由、流式传输 — 都是一个端点，你可以从任何你选择授予密钥的机器、团队成员或代理调用。

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

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

> **[Mac Studio setup](/zh/use-cases/mac-studio.md)**
>
> 将 Mac Studio 转变为无头推理服务器，利用统一内存运行 70B+ 模型。

## 参考来源

* [ml-explore/mlx-lm](https://github.com/ml-explore/mlx-lm) — MLX-LM Python 包和服务器的官方仓库
* [MLX-LM Server 文档（SERVER.md）](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/SERVER.md) — 服务器 API 参考和支持的端点
* [MLX 框架](https://github.com/ml-explore/mlx) — Apple Silicon 的底层数组框架
* [mlx-framework.org](https://mlx-framework.org/) — MLX 框架概述和生态系统链接
* [HuggingFace 上的 mlx-community](https://huggingface.co/mlx-community) — 预转换的可直接服务的 MLX 模型
* [探索 MLX 与 M5 中的 Neural Accelerators](https://machinelearning.apple.com/research/exploring-llms-mlx-m5) — Apple Machine Learning Research 关于 M5 ANE 性能的研究
* [在 Mac 上使用 MLX 运行本地代理 AI（WWDC26）](https://developer.apple.com/videos/play/wwdc2026/232/) — Apple 关于 MLX-LM Server、连续批处理和分布式推理的会话


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