# 本地与自托管提供商

本页覆盖运行在本机、内网，或由你自己托管且可被 LibreFang 直接访问的推理端点。

## 包含的提供商

- Ollama
- vLLM
- LM Studio

---

## Ollama

| | |
|---|---|
| **显示名称** | Ollama |
| **驱动** | OpenAI 兼容 |
| **环境变量** | `OLLAMA_API_KEY`（非必需） |
| **基础 URL** | `http://localhost:11434/v1` |
| **需要密钥** | **否** |
| **免费额度** | 免费（本地运行） |
| **认证方式** | 无（本地） |
| **模型数** | 3 个内置 + 自动发现 |

**可用模型（内置）：**
- `llama3.2` (本地)
- `mistral:latest` (本地)
- `phi3` (本地)

**设置：**
1. 从 [ollama.com](https://ollama.com) 安装 Ollama
2. 拉取模型：`ollama pull llama3.2`
3. 启动服务器：`ollama serve`
4. 无需设置环境变量 -- Ollama 始终可用

**说明：** LibreFang 会自动从运行中的 Ollama 实例发现模型，并以 `Local` 层级和零成本将其合并到目录中。任何你拉取的模型都会立即可用。

---

## vLLM

| | |
|---|---|
| **显示名称** | vLLM |
| **驱动** | OpenAI 兼容 |
| **环境变量** | `VLLM_API_KEY`（非必需） |
| **基础 URL** | `http://localhost:8000/v1` |
| **需要密钥** | **否** |
| **免费额度** | 免费（自托管） |
| **认证方式** | 无（本地） |
| **模型数** | 1 个内置 + 自动发现 |

**可用模型（内置）：**
- `vllm-local` (本地)

**设置：**
1. 安装 vLLM：`pip install vllm`
2. 启动服务器：`python -m vllm.entrypoints.openai.api_server --model <model-name>`
3. 无需设置环境变量

---

## LM Studio

| | |
|---|---|
| **显示名称** | LM Studio |
| **驱动** | OpenAI 兼容 |
| **环境变量** | `LMSTUDIO_API_KEY`（非必需） |
| **基础 URL** | `http://localhost:1234/v1` |
| **需要密钥** | **否** |
| **免费额度** | 免费（本地运行） |
| **认证方式** | 无（本地） |
| **模型数** | 1 个内置 + 自动发现 |

**可用模型（内置）：**
- `lmstudio-local` (本地)

**设置：**
1. 从 [lmstudio.ai](https://lmstudio.ai) 下载 LM Studio
2. 通过内置模型浏览器下载模型
3. 从 "Local Server" 标签页启动本地服务器
4. 无需设置环境变量

---

## Embedding 自动检测

embeddings 驱动设为 `provider = "auto"` 时，LibreFang 按优先级列表选第一个可达的 embeddings 后端。云 API key 优先；本地服务器在后。当前顺序(对照 `librefang-runtime::embedding::detect_embedding_provider` 验证):

1. `OPENAI_API_KEY` → `"openai"`
2. `OPENROUTER_API_KEY` → `"openrouter"`
3. `MISTRAL_API_KEY` → `"mistral"`
4. `TOGETHER_API_KEY` → `"together"`
5. `FIREWORKS_API_KEY` → `"fireworks"`
6. `COHERE_API_KEY` → `"cohere"`
7. `OLLAMA_HOST`(本地)
8. `VLLM_BASE_URL`(本地)
9. `LMSTUDIO_BASE_URL`(本地)

把 `OLLAMA_HOST` / `VLLM_BASE_URL` / `LMSTUDIO_BASE_URL` 任意一个设成可达的 URL 就够了——本地条目不需要 API key。`create_embedding_driver` 用同一优先级,所以 `auto` 启动时挑的跟显式 `provider = "vllm"` 构造的一致。

`GROQ_API_KEY` 故意**不**在梯队里 —— Groq 没有 `/v1/embeddings` 端点,自动选了它会在第一次真调时静默 404。同理,没有接通 embedding 驱动的 provider(`VOYAGE`、`JINA`、`MIXEDBREAD`、`BEDROCK` 自动挑选时 —— 显式配 Bedrock 是可以的)即使 chat key 设了也不会被自动选。

---

## 能力检测（Ollama 元数据流水线）

对 Ollama，LibreFang 在启动时和定期 provider 刷新时探测 `/api/tags`，从返回的 metadata 推导每个模型的能力：

| 能力 | 推导方式 |
|---|---|
| `vision` | model card 声明 image 输入 modality，或 family 在已知视觉列表里（`llava`、`bakllava`、`clip` 等） |
| `embedding` | model card 声明 embedding 专用架构（`nomic-embed-text`、`bge-m3`、`mxbai-embed-large` 等） |
| `tools` | model card 声明 tool-use 支持（较新的 Llama / Qwen / Mistral instruct 系列） |
| `parameter_size` | 从 Ollama tag 原样取（如 `7.6B`、`14.8B`） |
| `quantization_level` | 原样取（如 `Q4_K_M`、`F16`） |

dashboard 的 "Models" tab 和模型切换下拉里给每个模型显示这些 badge，它们也接进 `model_catalog` 的 `Modality` enum（`Text` / `Image` / `Audio`）——查询 image-generation 模型的调用方可以干净过滤，不用硬编码列表。

vLLM 和 LM Studio 通过它们的 OpenAI 兼容 `/models` 端点接同一探针，但 Ollama 路径填得最全，因为上游 API 暴露的数据最多。

### 重探周期

本地 provider 在启动时被探测，**每 60 秒在后台重探一次** — 所以 daemon 运行期间 `ollama pull` 的新模型不需要重启 daemon 就能出现在 catalog 里，停掉的本地服务器也会自动翻成 `auth_status: "local_offline"`。dashboard 中 provider 卡片上的**"Test connection"** 按钮会强制立即重探 + 缓存刷新，不用等下次定时 tick。
