# llm-proxy

**Repository Path**: snail_tech/llm-proxy

## Basic Information

- **Project Name**: llm-proxy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# next-ink

> **按需开启服务器的提供模型服务能力统一接口的管理平台**

## 特性
- **统一对外协议**：OpenAI Chat Completions 兼容（含 SSE 流式 + `[DONE]` 终止帧 + `usage` 字段）
- **三栈能力**：LLM 流式 / TTS 同步+异步 / ASR 同步+异步
- **计费三轴**：账号签到时长 + 实例小时消耗 + APIKey 额度（Redis Lua 原子扣减）
- **多渠道接入**：智普等 OpenAI 兼容渠道
- **实例生命周期**：5 态状态机 + 心跳 + 超时
- **CloudStudio 集成**：真实 API 适配器（只读验证通过 6/6）

## 技术栈
- **后端**：Python 3.11+ / FastAPI / asyncpg / redis-py / httpx / APScheduler
- **前端**：React 18 + Vite 5 + TypeScript
- **DB**：PostgreSQL 16（pgvector）+ Redis 7
- **包管理**：pnpm（前端）+ pip + venv（后端）

## 快速开始

### 1. 启动中间件
```bash
cd deploy && docker compose up -d
```
端口：PostgreSQL `15432` · Redis `16379`

### 2. 配置环境变量
```bash
cp .env.example .env
# 编辑 .env，填入 CLOUDSTUDIO_COOKIE 和 CLOUDSTUDIO_XSRF_TOKEN
```

### 3. 安装依赖
```bash
# 后端（Python venv）
cd app && python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]'

# 前端
cd .. && pnpm install
```

### 4. 数据库迁移
```bash
cd app && source .venv/bin/activate && python -m src.scripts.migrate
```

### 5. 启动开发服务
```bash
# 后端（终端 1）
cd app && source .venv/bin/activate && uvicorn src.main:app --host 0.0.0.0 --port 3191 --reload

# 前端（终端 2）
pnpm dev:web
```

或一条命令：
```bash
pnpm dev   # 需要先 source app/.venv/bin/activate
```

### 6. 验证 CloudStudio API 连通性
```bash
cd app && source .venv/bin/activate && python -m src.scripts.verify_cloudstudio
```

### 7. 访问
- 前端控制台：http://localhost:3190
- 后端 API：http://localhost:3191
- 健康检查：http://localhost:3191/health/ready

## 目录结构
```
.
├── app/                       # 后端 (Python/FastAPI)
│   ├── src/
│   │   ├── foundation/        # L1 基石（12 个 Python 模块）
│   │   ├── modules/           # L2 模块（12 个）
│   │   ├── orchestration/     # L3 编排（app/registry）
│   │   ├── routes/            # FastAPI 路由（11 组）
│   │   ├── middleware/        # 鉴权
│   │   ├── scripts/           # 迁移 + CloudStudio 验证
│   │   ├── tests/             # pytest 单元测试
│   │   └── main.py            # 入口
│   ├── pyproject.toml
│   └── .venv/                 # Python 虚拟环境
├── web/                       # 前端 (React + Vite)
├── deploy/                    # Docker Compose
├── contracts/README.md        # 契约索引
├── docs/taskbook.md           # 任务书
└── tests/                     # Playwright E2E
```

## 开发命令
| 命令 | 说明 |
|------|------|
| `pnpm dev:app` | 启动后端（uvicorn reload） |
| `pnpm dev:web` | 启动前端（vite） |
| `pnpm test` | 后端单元测试（pytest） |
| `pnpm db:migrate` | 初始化/迁移数据库 |
| `pnpm verify:cs` | CloudStudio API 验证（6 项只读测试） |
| `pnpm up` | 启动中间件 |
| `pnpm down` | 停止中间件 |

## 顶层对外 API（OpenAI 兼容）
```bash
# 模型列表
curl http://localhost:3191/v1/models -H "Authorization: Bearer sk-nextink-..."

# Chat Completion（非流式）
curl http://localhost:3191/v1/chat/completions \
  -H "Authorization: Bearer sk-nextink-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"nextink-llm-default","messages":[{"role":"user","content":"hi"}]}'

# Chat Completion（流式 SSE）
curl -N http://localhost:3191/v1/chat/completions \
  -H "Authorization: Bearer sk-nextink-..." \
  -d '{"model":"nextink-llm-default","messages":[{"role":"user","content":"hi"}],"stream":true}'

# TTS 异步
curl http://localhost:3191/v1/tts/async \
  -H "Authorization: Bearer sk-nextink-..." \
  -d '{"text":"你好","voice":"default"}'

# ASR 同步
curl http://localhost:3191/v1/asr/sync \
  -H "Authorization: Bearer sk-nextink-..." \
  -d '{"audioUrl":"https://.../a.mp3","language":"zh"}'
```