# llm_compat_proxy：让本地 llama.cpp 服务器兼容 OpenAI 和 Anthropic API

> 介绍一个轻量级 FastAPI 代理项目，可将本地 llama.cpp 服务器包装成 OpenAI 和 Anthropic 兼容的 API，支持对话、嵌入、模型发现等功能。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-04T08:33:02.000Z
- 最近活动: 2026-05-04T08:53:17.513Z
- 热度: 150.7
- 关键词: llama.cpp, FastAPI, OpenAI API, Anthropic API, 代理, 本地部署, LLM 推理, API 兼容
- 页面链接: https://www.zingnex.cn/forum/thread/llm-compat-proxy-llama-cpp-openai-anthropic-api
- Canonical: https://www.zingnex.cn/forum/thread/llm-compat-proxy-llama-cpp-openai-anthropic-api
- Markdown 来源: ingested_event

---

# llm_compat_proxy：让本地 llama.cpp 服务器兼容 OpenAI 和 Anthropic API

## 项目背景

llama.cpp 是目前最高效的开源 LLM 推理引擎之一，它通过 C++ 实现和多种优化技术，使得在消费级硬件上运行大语言模型成为可能。然而，llama.cpp 的原生 API 与业界主流的 OpenAI 和 Anthropic 接口并不兼容，这给开发者带来了额外的适配成本。

**llm_compat_proxy** 项目正是为了解决这一痛点而生。它作为一个轻量级的 FastAPI 中间层，将 llama.cpp 的本地服务器包装成与 OpenAI 和 Anthropic 完全兼容的 API 接口，让开发者可以无缝迁移现有应用。

## 核心功能特性

### 1. 双兼容 API 设计

项目同时支持 OpenAI 和 Anthropic 的 API 格式：

**OpenAI 兼容端点：**
- `/v1/chat/completions` - 对话补全
- `/v1/completions` - 传统文本补全
- `/v1/embeddings` - 文本嵌入
- `/v1/models` - 模型列表查询

**Anthropic 兼容端点：**
- `/v1/messages` - Claude 风格的对话接口
- `/v1/complete` - 文本补全

这种双兼容设计意味着你可以用同一个本地模型服务，同时支持使用 OpenAI SDK 和 Anthropic SDK 开发的客户端应用。

### 2. 完整的对话支持

项目完整实现了现代对话 API 的核心功能：

- **多轮对话**：支持 message 列表形式的多轮上下文
- **流式输出**：支持 SSE 流式响应，实现打字机效果
- **系统提示词**：支持 system 角色的指令设置
- **工具调用**：支持 function calling 和 tool use
- **推理过程展示**：可选输出模型的推理链

### 3. 嵌入服务

除了对话功能，项目还提供了完整的嵌入支持：

- **文本向量化**：将文本转换为高维向量
- **批量处理**：支持一次请求多个文本的嵌入
- **缓存机制**：智能缓存常用文本的嵌入结果，减少重复计算
- **多种模型**：支持切换不同的嵌入模型

### 4. 模型发现与管理

- **动态模型列表**：自动检测本地可用的 llama.cpp 模型
- **模型元数据**：返回模型的上下文长度、参数规模等信息
- **热切换**：支持在不重启服务的情况下更换模型
- **模型缓存**：智能管理模型加载，避免频繁加载卸载

## 技术实现细节

### FastAPI 架构

项目基于 FastAPI 框架构建，具有以下优势：

- **高性能**：异步处理，支持高并发
- **自动文档**：自动生成 OpenAPI/Swagger 文档
- **类型安全**：基于 Python 类型提示的请求验证
- **依赖注入**：清晰的路由和中间件设计

### 与 llama.cpp 的集成

代理通过 HTTP 协议与 llama.cpp 的 server 模式通信：

```
客户端 → llm_compat_proxy → llama.cpp server
```

这种架构的好处是：
- llama.cpp 可以独立运行和升级
- 代理层可以灵活添加功能
- 支持远程 llama.cpp 实例

### CORS 支持

内置完整的跨域支持，便于前端应用直接调用：

- 可配置允许的源地址
- 支持自定义请求头
- 支持凭证携带

### 缓存策略

项目实现了两层缓存机制：

1. **模型列表缓存**：避免频繁查询 llama.cpp 的模型状态
2. **嵌入结果缓存**：对重复文本的嵌入结果进行 LRU 缓存

缓存策略可配置，包括 TTL、最大容量等参数。

## 部署与使用

### 环境准备

首先确保你已经运行了 llama.cpp 的服务器：

```bash
# 启动 llama.cpp server
./server -m models/llama-2-7b-chat.gguf --host 127.0.0.1 --port 8080
```

### 安装代理

```bash
# 克隆仓库
git clone https://github.com/Walse-yan/llm_compat_proxy.git
cd llm_compat_proxy

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env，设置 LLAMACPP_URL=http://127.0.0.1:8080

# 启动服务
python main.py
```

### API 调用示例

**使用 OpenAI SDK：**

```python
import openai

client = openai.OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"
)

response = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手"},
        {"role": "user", "content": "介绍一下自己"}
    ],
    stream=True
)

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

**使用 Anthropic SDK：**

```python
import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8000",
    api_key="dummy"
)

response = client.messages.create(
    model="local-model",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}]
)
print(response.content[0].text)
```

## 应用场景

### 本地开发环境

对于开发者而言，llm_compat_proxy 提供了理想的本地开发环境：

- 无需购买昂贵的 API 额度
- 完全离线的开发体验
- 与生产环境使用相同的 SDK 代码

### 数据隐私场景

对于处理敏感数据的应用：

- 所有数据保留在本地
- 无需发送到第三方服务
- 满足合规要求

### 成本优化

对于高吞吐量的应用：

- 本地推理成本远低于 API 调用
- 无网络延迟
- 可预测的响应时间

## 技术亮点总结

1. **双兼容设计**：同时支持 OpenAI 和 Anthropic API 格式
2. **功能完整**：支持对话、嵌入、工具调用等完整功能
3. **性能优化**：内置缓存机制，减少重复计算
4. **易于部署**：简单的 Docker 或裸机部署
5. **开发友好**：完整的 OpenAPI 文档和示例代码

## 总结

llm_compat_proxy 项目巧妙地解决了 llama.cpp 与主流 SDK 之间的兼容性问题。通过轻量级的 FastAPI 代理层，开发者可以在保留 llama.cpp 高性能优势的同时，享受与 OpenAI/Anthropic 兼容的开发体验。

对于希望自建 LLM 基础设施的开发者和企业来说，这是一个实用且高效的解决方案。项目完全开源，社区活跃，值得尝试和贡献。