mock-openai-api
Version:
A mock OpenAI Compatible Provider API server
468 lines (360 loc) • 11.8 kB
Markdown
# Mock OpenAI API
[](https://www.npmjs.com/package/mock-openai-api)
[](https://github.com/zerob13/mock-openai-api/blob/main/LICENSE)
[](https://www.typescriptlang.org/)
[](https://expressjs.com/)
[](https://github.com/zerob13/mock-openai-api)
[](https://github.com/zerob13/mock-openai-api/fork)
*中文说明 | [English](README.md)*
一个完整的 OpenAI API 兼容的模拟服务器，无需调用真实的大模型，返回预定义的测试数据。非常适合开发、测试和调试使用 OpenAI API 的应用程序。
## 🚀 快速开始
### 方法 1：公共服务（无需安装配置）
最快的使用方式是直接使用我们的公共部署服务：
**服务地址**: `https://mockllm.anya2a.com/v1`
**API密钥**: `DeepChat`
```bash
# 测试公共服务
curl https://mockllm.anya2a.com/v1/models \
-H "Authorization: Bearer DeepChat"
# 聊天完成示例
curl -X POST https://mockllm.anya2a.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DeepChat" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "你好"}]
}'
```
### 方法 2：NPM 安装（本地部署）
```bash
npm install -g mock-openai-api
```
### 启动服务器
```bash
npx mock-openai-api
```
服务器将在 `http://localhost:3000` 启动。
## ⚙️ CLI 选项
模拟服务器支持多种命令行选项进行自定义配置：
### 基本用法
```bash
# 使用默认设置启动
npx mock-openai-api
# 指定自定义端口启动
npx mock-openai-api -p 8080
# 指定自定义主机和端口
npx mock-openai-api -H localhost -p 8080
# 启用详细请求日志
npx mock-openai-api -v
# 组合多个选项
npx mock-openai-api -p 8080 -H 127.0.0.1 -v
```
### 可用选项
| 选项 | 简写 | 描述 | 默认值 |
| ------------------ | ---- | ------------------------ | --------- |
| `--port <number>` | `-p` | 服务器端口 | `3000` |
| `--host <address>` | `-H` | 服务器主机地址 | `0.0.0.0` |
| `--verbose` | `-v` | 启用请求日志输出到控制台 | `false` |
| `--version` | | 显示版本号 | |
| `--help` | | 显示帮助信息 | |
### 使用示例
```bash
# 开发环境设置，启用详细日志
npx mock-openai-api -v -p 3001
# 生产环境设置
npx mock-openai-api -H 0.0.0.0 -p 80
# 本地测试设置
npx mock-openai-api -H localhost -p 8080 -v
# 查看版本
npx mock-openai-api --version
# 获取帮助
npx mock-openai-api --help
```
服务器启动时，会显示正在使用的配置：
```
🚀 Mock OpenAI API server started successfully!
📍 Server address: http://0.0.0.0:3000
⚙️ Configuration:
• Port: 3000
• Host: 0.0.0.0
• Verbose logging: DISABLED
• Version: 1.0.1
```
### 基本使用
```bash
# 获取模型列表
curl http://localhost:3000/v1/models
# 聊天完成（非流式）
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "你好"}]
}'
# 聊天完成（流式）
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "你好"}],
"stream": true
}'
# 图像生成
curl -X POST http://localhost:3000/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "一只可爱的猫咪",
"n": 1,
"size": "1024x1024"
}'
```
## 🎯 特性
- ✅ **完整的 OpenAI API 兼容性**
- ✅ **支持流式和非流式聊天完成**
- ✅ **支持函数调用**
- ✅ **支持图像生成**
- ✅ **预定义的测试场景**
- ✅ **TypeScript 编写**
- ✅ **易于集成和部署**
- ✅ **详细的错误处理**
## 📋 支持的 API 端点
### 模型管理
- `GET /v1/models` - 获取可用模型列表
- `GET /models` - 兼容端点
### 聊天完成
- `POST /v1/chat/completions` - 创建聊天完成
- `POST /chat/completions` - 兼容端点
### 图像生成
- `POST /v1/images/generations` - 生成图像
- `POST /images/generations` - 兼容端点
### 健康检查
- `GET /health` - 服务器健康状态
## 🤖 可用模型
### 1. mock-gpt-thinking
**思考型模型** - 显示推理过程，适合调试逻辑
```json
{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "计算 2+2"}]
}
```
响应会包含 `<thinking>` 标签显示思考过程。
### 2. gpt-4-mock
**函数调用模型** - 支持工具和函数调用
```json
{
"model": "gpt-4-mock",
"messages": [{"role": "user", "content": "今天北京的天气怎么样？"}],
"functions": [
{
"name": "get_weather",
"description": "获取天气信息",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"},
"date": {"type": "string"}
}
}
}
]
}
```
### 3. mock-gpt-markdown
**Markdown 示例模型** - 专门输出标准 Markdown 格式的纯文本模型
```json
{
"model": "mock-gpt-markdown",
"messages": [{"role": "user", "content": "任何问题"}]
}
```
响应将是一个完整的 Markdown 文档，包含各种格式元素，适合前端 UI 调试。
**注意：** 此模型专注于内容展示，不支持函数调用功能，保持输出的纯净性。
### 4. gpt-4o-image
**图像生成模型** - 专门用于图像生成
```json
{
"model": "gpt-4o-image",
"prompt": "一只可爱的橘猫在阳光下玩耍",
"n": 2,
"size": "1024x1024",
"quality": "hd"
}
```
支持多种尺寸和质量设置，返回高质量的模拟图像。
## 🛠️ 开发
### 本地开发
```bash
# 克隆项目
git clone https://github.com/zerob13/mock-openai-api.git
cd mock-openai-api
# 安装依赖
npm install
# 开发模式运行
npm run dev
# 构建项目
npm run build
# 生产模式运行
npm start
```
### 项目结构
```
src/
├── types/ # TypeScript 类型定义
├── data/ # 预定义的测试数据
├── utils/ # 工具函数
├── services/ # 业务逻辑服务
├── controllers/ # 路由控制器
├── routes/ # 路由定义
├── app.ts # Express 应用设置
├── index.ts # 服务器启动
└── cli.ts # CLI 工具入口
```
### 添加新的测试场景
1. 在 `src/data/mockData.ts` 中添加新的测试用例
2. 可以为现有模型添加测试用例，或创建新的模型类型
3. 重新构建项目：`npm run build`
示例：
```typescript
const newTestCase: MockTestCase = {
name: "新功能测试",
description: "测试新功能的描述",
prompt: "触发关键词",
response: "预期的响应内容",
streamChunks: ["分段", "流式", "内容"], // 可选
functionCall: { // 可选，仅用于 function 类型模型
name: "function_name",
arguments: { param: "value" }
}
};
```
## 🌐 部署
### Docker 部署
创建 `Dockerfile`:
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]
```
构建和运行：
```bash
docker build -t mock-openai-api .
docker run -p 3000:3000 mock-openai-api
```
### 环境变量
- `PORT` - 服务器端口（默认：3000）
- `HOST` - 服务器主机（默认：0.0.0.0）
## 🧪 测试
### 使用 curl 测试
```bash
# 测试公共服务
curl https://mockllm.anya2a.com/health
curl https://mockllm.anya2a.com/v1/models \
-H "Authorization: Bearer DeepChat"
# 测试本地服务
curl http://localhost:3000/health
curl http://localhost:3000/v1/models
# 测试思考型模型
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "解释一下递归"}]
}'
# 测试函数调用
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4-mock",
"messages": [{"role": "user", "content": "现在几点了？"}]
}'
# 测试 Markdown 输出
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-markdown",
"messages": [{"role": "user", "content": "任何内容"}]
}'
# 测试流式输出
curl -X POST http://localhost:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mock-gpt-thinking",
"messages": [{"role": "user", "content": "讲个故事"}],
"stream": true
}'
# 测试图像生成
curl -X POST http://localhost:3000/v1/images/generations \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "一只可爱的橘猫",
"n": 2,
"size": "1024x1024"
}'
```
### 使用 OpenAI SDK 测试
```javascript
import OpenAI from 'openai';
// 使用公共服务
const client = new OpenAI({
baseURL: 'https://mockllm.anya2a.com/v1',
apiKey: 'DeepChat'
});
// 或使用本地部署
const localClient = new OpenAI({
baseURL: 'http://localhost:3000/v1',
apiKey: 'mock-key' // 可以是任意值
});
// 测试聊天完成
const completion = await client.chat.completions.create({
model: 'mock-gpt-thinking',
messages: [{ role: 'user', content: '你好' }]
});
console.log(completion.choices[0].message.content);
// 测试流式聊天
const stream = await client.chat.completions.create({
model: 'mock-gpt-thinking',
messages: [{ role: 'user', content: '你好' }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || '';
process.stdout.write(content);
}
// 测试图像生成
const image = await client.images.generate({
model: 'gpt-4o-image',
prompt: '一只可爱的橘猫',
n: 1,
size: '1024x1024'
});
console.log(image.data[0].url);
```
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本项目
2. 创建特性分支：`git checkout -b feature/AmazingFeature`
3. 提交更改：`git commit -m 'Add some AmazingFeature'`
4. 推送到分支：`git push origin feature/AmazingFeature`
5. 提交 Pull Request
## 📄 许可证
本项目使用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
## 🔗 相关链接
- [OpenAI API 文档](https://platform.openai.com/docs/api-reference)
- [Express.js](https://expressjs.com/)
- [TypeScript](https://www.typescriptlang.org/)
## 💡 使用场景
- **前端开发**: 无需等待后端 API，快速开发和测试 AI 功能
- **API 集成测试**: 验证应用程序与 OpenAI API 的集成
- **演示和原型**: 创建不依赖真实 AI 服务的演示
- **开发调试**: 调试流式响应、函数调用等复杂场景
- **成本控制**: 避免开发阶段的 API 调用费用
- **离线开发**: 在没有网络的情况下开发 AI 应用
## 🎉 结语
Mock OpenAI API 让您能够快速、可靠地开发和测试 AI 应用，无需担心 API 配额、网络连接或费用问题。开始您的 AI 应用开发之旅吧！