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

# 本地 LLM API（locallm API）：通过 OpenAI 兼容端点暴露你的模型

> 为你的本地模型（locallm）提供经过身份验证的 OpenAI 兼容 API 端点。比较各方案（Tokios、LiteLLM、LocalAI），几分钟内即可完成团队访问设置。

你的本地模型运行在 `localhost:11434` 或 `localhost:8000` 上。对你自己来说没问题，但你的团队、应用和远程客户端无法访问它。你需要一个 **本地 LLM API**（也写作 **locallm API**）——一个经过身份验证的 OpenAI 兼容端点，让任何持有 API key 的人都能从任何地方调用你的本地模型。

本指南介绍什么是本地 LLM API、创建它的各种方案，以及如何设置带有按用户身份验证和模型作用域的团队访问。

最后验证：2026-10-24

## API 差距

当你使用 Ollama、vLLM、llama.cpp 或 LM Studio 运行模型时，你会在 `127.0.0.1:PORT/v1` 上获得一个本地 API。这对运行模型的机器有效，但它无法解决以下问题：

* **远程访问** ——你的团队无法从笔记本电脑通过 `127.0.0.1` 进行访问
* **身份验证** ——运行时没有按用户的身份验证（或者只有一个共享密钥）
* **模型作用域** ——每个人都能访问所有模型，或者所有人都无法访问
* **网络** ——端口转发、Tailscale、Cloudflare Tunnel、CGNAT

一个 **本地 LLM API** 填补了这一空白。它位于你的运行时和客户端之间，提供：

* 一个路由到你本地模型的公共端点（例如 `https://api.tokios.com/v1`）
* 带有模型作用域的按用户 API key
* 仅出站隧道（无需入站端口）
* OpenAI 兼容接口（任何 OpenAI SDK 都可用）

## 什么是本地 LLM API？

本地 LLM API 是一个 API 层，它通过经过身份验证的 OpenAI 兼容端点将你本地运行的语言模型暴露给远程客户端。它通常包括：

* **身份验证** ——识别每个用户或应用的 API key（`sk-tok-…` 或类似格式）
* **授权** ——模型作用域（谁可以访问哪些模型）
* **路由** ——将公共部署名称映射到上游模型 id
* **协议转换** ——在需要时在不同 API 格式之间转换
* **隧道** ——将你的本地运行时连接到公共端点，无需入站端口

结果是：你的团队通过 `https://api.tokios.com/v1` 使用 API key 并指定部署名称（例如 `team-llama`），请求经隧道路由到你的本地模型。

## 暴露本地模型的方案

### 原始运行时 API

Ollama、vLLM、llama.cpp 和 LM Studio 都在 localhost 上暴露 OpenAI 兼容的 `/v1` API。这是最简单的方案，但存在局限性：

* **无身份验证**（Ollama）或**单个共享密钥**（vLLM、llama.cpp、LM Studio）
* **仅限 localhost** ——没有额外的网络配置就无法远程访问
* **无模型作用域** ——每个人都能访问所有模型
* **无按用户追踪** ——无法分辨谁在发起请求

**适用于：** 个人使用、单机设置、开发和测试

**不适用于：** 团队访问、远程客户端、生产工作负载

### LiteLLM

[LiteLLM](https://github.com/BerriAI/litellm) 是一个开源代理，为 100+ 个 LLM（本地和云端）提供 OpenAI 兼容 API。它是 r/LocalLLaMA 社区中的热门选择。

**优势：**

* 多提供商路由（一个端点同时支持本地 + 云端）
* OpenAI 兼容接口
* 负载均衡和故障转移
* 活跃的社区

**局限性：**

* 代理模式 ——你的客户端调用 LiteLLM，LiteLLM 调用运行时。两者都需要可达。
* 无内置隧道 ——你仍需解决网络问题（Tailscale、Cloudflare Tunnel 等）
* 单个共享 API key（开箱即无按用户身份验证）
* 自托管 ——你需要运行代理服务器

**适用于：** 多提供商设置（本地 + 云端），有能力管理自己代理的团队

**不适用于：** 希望使用托管方案的团队，CGNAT 后的用户，非技术用户

完整对比请参见 [Tokios vs LiteLLM](https://docs.tokios.com/zh/guides/tokios-vs-litellm.md)。

### LocalAI

[LocalAI](https://github.com/mudler/LocalAI) 是一个自托管的 OpenAI 兼容 API 服务器，支持多种模型格式和模态（文本、图像、音频、视频）。

**优势：**

* 广泛的模态支持（文本、图像、音频、视频）
* OpenAI 兼容接口
* 自托管，注重隐私
* 活跃的开发

**局限性：**

* 自托管 ——你需要运行服务器
* 无内置隧道 ——你仍需解决网络问题
* 单个共享 API key（无按用户身份验证）
* 比 Ollama 或 vLLM 设置更复杂

**适用于：** 多模态工作负载（文本 + 图像 + 音频），希望自托管 OpenAI 替代方案的团队

**不适用于：** 希望使用托管基础设施的团队，CGNAT 后的用户，简单的纯文本用例

### Tokios

Tokios 是一个专为团队访问本地模型而设计的隧道 + API 网关。它提供：

* **仅出站隧道** ——连接器主动拨出，因此无需入站端口、无需端口转发、无需 Tailscale。可在 CGNAT、企业防火墙和 NAT 后工作。
* **按用户 API key** ——每个团队成员获得自己的 `sk-tok-…` key，并限定到特定模型
* **模型路由** ——通过一个端点提供多个模型（Ollama、vLLM、llama.cpp）
* **OpenAI 兼容端点** ——`https://api.tokios.com/v1` 可与任何 OpenAI SDK 配合使用
* **托管基础设施** ——无需运行代理服务器，无需配置隧道

**优势：**

* 专为团队访问本地模型而构建
* 无网络问题（仅出站隧道）
* 按用户身份验证和模型作用域
* 可在 CGNAT 后工作（Starlink、5G、公寓 ISP）
* 托管服务 ——无需维护基础设施

**局限性：**

* 需要互联网访问（隧道需要出站连接）
* 不适合隔离网络环境
* 托管服务（非自托管）

**适用于：** 希望与远程访问共享本地模型的团队，CGNAT 后的用户，希望简单设置的非技术用户

**不适用于：** 隔离网络环境，要求自托管基础设施的团队，多云路由

## 对比矩阵

| 功能 | 原始运行时 | LiteLLM | LocalAI | Tokios |
| - | - | - | - | - |
| **身份验证** | 无或单个密钥 | 单个密钥 | 单个密钥 | 按用户 API key |
| **模型作用域** | 否 | 否 | 否 | 是 |
| **网络** | 仅 localhost | 自行管理 | 自行管理 | 仅出站隧道 |
| **CGNAT 支持** | 否 | 手动 | 手动 | 自动 |
| **远程访问** | 否 | 是（需隧道） | 是（需隧道） | 是（内置） |
| **多模型路由** | 否 | 是 | 是 | 是 |
| **多提供商** | 否 | 是 | 否 | 否（仅本地） |
| **设置复杂度** | 低 | 中 | 中高 | 低 |
| **基础设施** | 无 | 自托管代理 | 自托管服务器 | 托管 |
| **OpenAI 兼容** | 是 | 是 | 是 | 是 |

## 使用 Tokios 设置本地 LLM API

**1. 在模型主机上安装连接器**

在运行模型的机器上（Ollama、vLLM、llama.cpp、LM Studio），安装 Tokios 连接器：

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

你的一次性认领代码 `TKS-XXXX-XXXX` 可在 [dashboard](https://tokios.com/console) 的 **Setup** 标签页获取。

**2. 认领连接器并指向你的运行时**

在 dashboard 中，**approve** 该设备。然后配置连接器指向你运行时的本地 API：

* Ollama: `http://127.0.0.1:11434/v1`
* vLLM: `http://127.0.0.1:8000/v1`
* llama.cpp: `http://127.0.0.1:8080/v1`
* LM Studio: `http://127.0.0.1:1234/v1`

**3. 将你的模型注册为部署**

在 **Models** 标签页上，将每个上游模型 id（例如 `llama3.1`）映射到一个公共部署名称（例如 `team-llama`）。客户端在 `model` 字段中发送部署名称。

**4. 为你的团队创建 API key**

在 **Keys** 标签页上，为每个团队成员创建一个 key。将每个 key 限定到特定部署。将 key 和端点 URL（`https://api.tokios.com/v1`）分享给你的团队。

你的团队现在可以从任何地方调用你的本地模型：

```python 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="team-llama",
    messages=[{"role": "user", "content": "Hello from the team laptop"}],
)
```

完整演练请参见 [团队访问本地模型](https://docs.tokios.com/zh/use-cases/team-access.md)。

## 客户端集成示例

```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": "team-llama",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

```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="team-llama",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
```

```javascript OpenAI SDK theme={"theme":{"light":"github-light","dark":"css-variables"}}
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.tokios.com/v1',
  apiKey: 'sk-tok-YOUR_KEY',
});

const response = await client.chat.completions.create({
  model: 'team-llama',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(response.choices[0].message.content);
```

```typescript Anthropic SDK theme={"theme":{"light":"github-light","dark":"css-variables"}}
import Anthropic from '@anthropic-ai/sdk';

const client = Anthropic({
  baseURL: 'https://api.tokios.com/v1',
  apiKey: 'sk-tok-YOUR_KEY',
});

// Tokios translates Anthropic API calls to your local model
const response = await client.messages.create({
  model: 'team-llama',
  max_tokens: 100,
  messages: [{ role: 'user', content: 'Hello' }],
});
```

任何 OpenAI 兼容客户端都可以使用 —— Python SDK、JavaScript SDK、curl、Continue、Cline、Open WebUI，以及 [更多客户端](https://docs.tokios.com/zh/guides/compatible-clients.md)。

## 常见问题

> **我可以使用任何 OpenAI 兼容客户端吗？**
>
> 可以。任何支持 OpenAI `/v1` API 的客户端都可以使用 —— Python SDK、JavaScript SDK、curl、Continue、Cline、Open WebUI、Cherry Studio 等等。完整列表请参见 [兼容客户端](https://docs.tokios.com/zh/guides/compatible-clients.md)。

> **流式响应呢？**
>
> Tokios 正确处理流式传输。在请求中设置 `"stream": true`，响应将逐 token 流式传输。某些隧道方案（Cloudflare Tunnel）存在 SSE 缓冲问题，会破坏流式传输 ——详情请参见 [隧道与流式传输](https://docs.tokios.com/zh/guides/tunnels-and-streaming.md)。

> **我可以提供多个模型吗？**
>
> 可以。注册多个部署（例如 `team-llama`、`team-qwen`、`team-coder`）并将它们路由到不同的上游模型。你甚至可以通过同一端点提供来自不同运行时（Ollama + vLLM + llama.cpp）的模型。请参见 [模型路由](https://docs.tokios.com/zh/guides/model-routing.md)。

> **如何处理身份验证？**
>
> Tokios 提供按用户 API key。为每个团队成员创建一个 key，将其限定到特定模型，并安全地分享。你可以撤销任何 key 而不影响其他 key。完整详情请参见 [API key](https://docs.tokios.com/zh/setup/api-keys.md)。

> **本地 LLM API 和云端 API 有什么区别？**
>
> 本地 LLM API 将你本地运行的模型暴露给远程客户端。模型运行在你的硬件上，你的数据保留在你的网络上，你控制基础设施。云端 API（OpenAI、Anthropic）在他们的服务器上运行模型 ——你通过互联网发送数据，他们运行推理，你按 token 付费。

> **我可以将它与 LiteLLM 或 LocalAI 一起使用吗？**
>
> Tokios 是 LiteLLM 和 LocalAI 的替代方案，而非补充。如果你已经在使用 LiteLLM 或 LocalAI，可以用 Tokios 替换它们以获得更简单的团队访问。如果你需要多提供商路由（本地 + 云端），可以将 Tokios 与 LiteLLM 配合使用 ——请参见 [Tokios vs LiteLLM](https://docs.tokios.com/zh/guides/tokios-vs-litellm.md)。

## 后续步骤

* [团队访问本地模型](https://docs.tokios.com/zh/use-cases/team-access.md) ——为团队提供 API 访问的完整演练
* [API key 参考](https://docs.tokios.com/zh/setup/api-keys.md) ——作用域、分享和撤销
* [模型路由](https://docs.tokios.com/zh/guides/model-routing.md) ——通过一个端点提供多个模型
* [Tokios vs LiteLLM](https://docs.tokios.com/zh/guides/tokios-vs-litellm.md) ——详细对比
* [兼容客户端](https://docs.tokios.com/zh/guides/compatible-clients.md) ——找到你的客户端


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