> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/sdk/local-inference · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 本地推理与自托管

Ollama、vLLM、llama.cpp server、LM Studio、SGLang、TGI 这类**本地/自托管推理服务不是客户端 SDK，而是上游**。它们跑模型、暴露一个（通常是 OpenAI 兼容的）HTTP 端点；网关把它们的端点配成一个上游，你的客户端侧仍用 [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md) 或任意框架，完全不用改。

```
客户端（任意 SDK） ──> 网关（openai 兼容上游） ──> 自托管服务（Ollama/vLLM/...）
      base_url → 网关            upstream → http://<host>:11434/v1
```

## 通用接法 {#generic}

1. 起好本地服务（下面各自一行）。
2. 控制台 → **上游服务** → 新建，协议选 `openai`，基础 URL 填本地服务地址，其余按需。
3. 建模型、配密钥组、签发访问密钥——与 [接入 OpenAI 上游](/zh-CN/quickstart/openai-compatible.md) 步骤完全一致。
4. 客户端用 OpenAI SDK，`base_url` 指到网关，`model` 填网关模型名。

## Ollama {#ollama}

```bash
ollama serve                      # 默认监听 http://localhost:11434
ollama pull qwen3:8b
```

> **坑：Ollama 原生 `/api/chat` 不是 OpenAI 兼容**。给网关配上游时，基础 URL 要用 OpenAI 兼容路径 `http://localhost:11434/v1`（带 `/v1`），不能填 `http://localhost:11434`。

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:7890/v1", api_key="<你的访问密钥>")
resp = client.chat.completions.create(
    model="qwen3-8b",   # 网关里配的模型名，上游模型 ID 是 Ollama 的 qwen3:8b
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)
```

## vLLM {#vllm}

```bash
vllm serve Qwen/Qwen3-8B --port 8000   # OpenAI 兼容端点在 http://localhost:8000/v1
```

vLLM 原生就是 OpenAI 兼容（`/v1/chat/completions`），上游基础 URL 填 `http://localhost:8000/v1`。它的 rerank / embedding 端点（`/v1/rerank`、`/v1/embeddings`）对应网关的 `openai_rerank` / `openai_embeddings` 协议——要给 vLLM 的 rerank 模型单独建一个 `openai_rerank` 协议的上游与模型。

## llama.cpp server {#llamacpp}

```bash
llama-server -m model.gguf --port 8080   # OpenAI 兼容端点在 http://localhost:8080/v1
```

同上，上游基础 URL 填 `http://localhost:8080/v1`。

## SGLang / TGI / LM Studio {#others}

- **SGLang**：`python -m sglang.launch_server ... --port 30000`，OpenAI 兼容端点 `/v1`。
- **TGI（Hugging Face）**：`text-generation-launcher`，兼容端点 `/v1`（部分版本仅 `/generate`，需用 `passthrough` 协议兜底）。
- **LM Studio**：本地 GUI 起 server，勾选「OpenAI 兼容」，默认 `http://localhost:1234/v1`。

接法一致：协议 `openai`，基础 URL 填它的 `/v1` 端点。若某服务只有**非 OpenAI 兼容**的原生端点（少数 TGI / 私有实现），改配 `passthrough` 协议原样转发，客户端走 `/v3/{model}/{*rest}` 或 `/v1/services/*`，见 [端点](/zh-CN/reference/endpoints.md)。

## 为什么经网关跑本地模型 {#why}

- **统一入口**：本地模型与云端模型混用同一个 base_url，客户端零改动切换。
- **复用能力**：负载均衡、访问控制、计费、可观测性对本地上游同样生效。
- **离线/数据合规**：模型不出内网，网关只做路由与治理。

## 下一步 {#next}

- 配一个 `openai` 兼容上游的完整步骤：见 [接入 OpenAI 上游](/zh-CN/quickstart/openai-compatible.md)。
- 多个本地/云端上游之间的负载均衡与故障转移：见 [多上游负载均衡](/zh-CN/quickstart/multi-upstream-load-balancing.md)。