拼好 AI：个人用户的轻量化 AI 模型聚合平台

发表于 2025-10-18 更新于 2026-02-28 Waline：

前言

做这个项目的初衷，其实是为了把各处“白嫖”来的公益站资源做个整合。毕竟“嫖”来的接口稳定性难免波动，所以我需要一个能方便调用并支持故障转移的工具。为此，我尝试了一些开源的 API 网关，比如 New API 和 uni-api。

起初我选择了 New API，毕竟它是众多公益站的首选，功能确实强大且全面。但“成也萧何败也萧何”，对于我这种个人用户来说，它显得有些过于臃肿了。于是我开始寻找更轻量级的替代品，最终发现了 uni-api。

如果说 New API 是“大而全”，那 uni-api 绝对算得上“小而美”。它摒弃了复杂的功能，保留了核心需求。我使用了一段时间，体验总体不错。唯独在本地部署时遇到了前端 CORS 跨域问题（HTTPS 站点无法请求 HTTP 内容），导致官方提供的前端无法连接。正是这个前端问题，让我萌生了自己动手开发一个类似项目的念头。

拼好 AI

拼好 AI 是一个专为个人用户打造的轻量级 AI 模型聚合平台，其核心功能基于任意门项目构建。

核心特性

多源聚合：统一管理多个 AI 服务提供商，支持 OpenAI、Anthropic 和 Gemini 协议格式。
Multi 统一接口：提供统一的 API 网关，支持 OpenAI、Anthropic 和 Gemini 三种 API 格式自动识别。
原生接口模式：支持直接透传请求，保留原始 API 响应，适合需要平台特定功能的场景。
智能负载：支持自动负载均衡，有效分散请求压力。
高可用性：内置故障转移机制，自动切换至可用服务，保障服务连续性。
健康监控：实时监控平台、密钥、模型的健康状态，支持一键恢复异常。
极简部署：支持 Docker 一键部署，配置门槛低。
数据存储：默认使用 SQLite，同时支持 MySQL 和 PostgreSQL（含 TLS 加密连接）。
可视化管理：内置直观的 Web 管理界面，操作便捷。
高级配置：支持模型名称映射、批量重命名、UA 透传/覆盖等灵活配置。

部署指南

Docker 部署

推荐使用 Docker 进行部署，这是最简单快捷的方式：

# 拉取并运行最新版本（请自行设置 token）
docker run -d \
  -p 3000:3000 \
  -e ENABLE_WEB=true \
  -e API_TOKEN=<业务token> \
  -e ADMIN_TOKEN=<管理token> \
  ghcr.io/meowsalty/pinai:latest

如果需要持久化数据，请将 PinAI 的数据目录 /app/data 映射到宿主机的目录。

环境变量配置

环境变量	说明	默认值
`ENABLE_WEB`	启用内置 Web 管理界面	`false`
`API_TOKEN`	业务 Token，用于 API 调用鉴权	无
`ADMIN_TOKEN`	管理 Token，用于管理 API 访问	无
`GITHUB_PROXY`	GitHub 代理地址，用于解决网络问题	无
`MODEL_MAPPING`	模型映射配置	无
`USER_AGENT`	User-Agent 配置（见下方说明）	空（透传）
`DB_TYPE`	数据库类型 (sqlite, mysql, postgres)	`sqlite`
`DB_SSL_MODE`	PostgreSQL SSL 模式 (disable, require, verify-ca, verify-full)	`disable`
`DB_TLS_CONFIG`	MySQL TLS 配置 (true, false, skip-verify, preferred)	`false`
`LOG_LEVEL`	日志输出等级 (DEBUG, INFO, WARN, ERROR)	`INFO`

此处并非完整的配置列表，完整列表请参考项目自述文件。

数据库配置

默认数据库：SQLite（数据目录：/app/data）
可选数据库：MySQL、PostgreSQL
TLS 支持：MySQL 和 PostgreSQL 支持 TLS 加密连接
数据持久化：建议将 /app/data 目录映射到宿主机

鉴权机制 (Token)

业务 Token：用于常规 API 调用时的身份验证。
管理 Token：用于访问管理接口。若未单独设置，默认复用业务 Token。
无鉴权模式：若两者均未设置，系统将运行在无鉴权模式下（不推荐在公网环境使用）。

网络配置建议

前端访问：
- 内置前端：设置 ENABLE_WEB=true 即可启用，适合本地单机部署。
- 独立前端：可选择自行部署或直接使用预览站点。
网络加速：
- Docker 镜像：若无法访问 GitHub Container Registry，可使用南京大学镜像源：ghcr.nju.edu.cn/meowsalty/pinai:latest。
- GitHub 代理：若服务器无法直接访问 GitHub，建议配置代理地址，例如：https://gh-proxy.com。

模型映射

针对部分强制要求特定模型名称的应用（如 Claude Code），系统提供了模型映射功能。

配置格式：原始模型名:目标模型名,原始模型名2:目标模型名2
工作原理：启用后，系统会在转发请求前，自动将请求中的“原始模型名”替换为配置的“目标模型名”。

示例：在 Claude Code 中使用 DeepSeek 模型

# 环境变量方式
export MODEL_MAPPING="claude-sonnet-4-20250514:deepseek-v3"

# Docker 方式
docker run -d \
  -p 3000:3000 \
  -e MODEL_MAPPING="claude-sonnet-4-20250514:deepseek-v3" \
  ghcr.io/meowsalty/pinai:latest

User-Agent 策略

该配置用于控制转发给上游 AI 服务时的 User-Agent 请求头。支持以下三种模式：

透传模式（默认）：若不设置或留空，系统将直接透传客户端的 User-Agent。
默认模式：设置为 default 时，不手动添加 User-Agent 头，使用底层 HTTP 库（fasthttp）的默认值。
自定义模式：设置为其他字符串时，将使用该字符串作为 User-Agent。

可通过设置 USER_AGENT 环境变量来调整此策略。

快速开始

初始化配置

访问界面：在浏览器中打开 http://127.0.0.1:3000。
连接设置：
- 点击页面顶部的“默认 API 服务器”。
- 在弹窗中配置服务器信息。
- API 密钥：输入您在环境变量中设置的 Token（优先使用 ADMIN_TOKEN）。
保存生效：保存配置并刷新页面。
添加服务：点击侧边栏的“供应商”菜单，开始添加 API 服务提供商。

API 接口调用

拼好 AI 提供 Multi 统一接口，支持 OpenAI、Anthropic 和 Gemini 三种 API 格式：

接口类型	基础路径	说明
兼容接口	`/multi/v1`	自动转换请求/响应格式
原生接口	`/multi/native/v1`	直接透传请求，保留原始响应

OpenAI 格式示例：

curl https://your-domain.com/multi/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Anthropic 格式示例：

curl https://your-domain.com/multi/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Gemini 格式示例：

curl https://your-domain.com/multi/v1beta/models/gemini-pro:generateContent \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: YOUR_API_TOKEN" \
  -d '{
    "contents": [{"parts": [{"text": "Hello!"}]}]
  }'

注意：旧的 /openai/v1 和 /anthropic/v1 接口已弃用，将在未来版本中移除，请迁移至 Multi 接口。

管理界面详解

拼好 AI 提供了一个功能完整的 Web 管理界面，主要分为四个核心模块：

仪表盘

仪表盘提供了系统的全景视图，包含三个核心维度：

1. 实时监控

QPS (调用频率)：展示最近 1 分钟内的 API 请求速率。
并发连接：显示当前活跃的连接数。

实时状态

2. 统计概览 (24H)

展示最近 24 小时内的关键性能指标：

总请求数：模型调用的累计次数。
请求成功率：成功响应的请求占比。
平均 TTFT：流式请求的平均首字时间 (Time to First Token)，不包含故障转移耗时。
Token 消耗：输入 (Prompt) 和输出 (Completion) 的 Token 统计。

统计概览

3. 用量排行 (Top 5)

展示最近 24 小时内的数据排行：

热门模型：调用次数最多的模型。
活跃平台：调用次数最多的供应商平台。
模型消耗：Token 用量最大的模型。
平台消耗：Token 用量最大的平台。

排行信息

供应商

供应商管理模块支持完整的增删改查 (CRUD) 操作，并集成了以下高级功能：

1. 批量导入

支持通过 CSV 格式快速导入供应商信息：

1	[类型],[名称],[端点],[密钥]

批量导入供应商

字段说明：

类型：支持 OpenAI、Anthropic 或 Gemini。
名称：供应商的标识名称。
端点：API Base URL（例如：https://api.example.com）。
密钥：API Key。

高级选项：

自动获取模型：导入时自动拉取该供应商的模型列表。
模型自动重命名：应用预设规则自动重命名模型。
快捷端点配置：根据供应商类型自动配置多个 API 端点。
- OpenAI：chat_completions + responses
- NewAPI/DoneHub：openai + google + anthropic 多端点
- 其他供应商：自动匹配对应的端点类型

2. 模型自动同步

在供应商编辑页，点击“获取模型”即可同步上游模型列表。

模型变更

功能特性：

自动对比现有模型列表，展示差异。
支持选择性更新，避免覆盖自定义配置。

3. 模型名称重写 (Rewrite)

系统支持强大的模型名称重写引擎，包含四种处理模式：

插入：在指定位置插入字符。
替换：简单的字符串替换。
正则：基于正则表达式的高级替换。
大小写：统一转换为大写或小写。

规则执行逻辑：

规则链按顺序自上而下执行。
支持拖拽排序及单独启用/禁用。

默认预设规则：

默认规则

全转小写
移除分组标识
统一使用连字符
移除日期后缀

正则配置示例：

// 目标：将 claude-3-7-sonnet 转换为 claude-sonnet-3.7

// 步骤 1：调整系列名位置
正则：`^claude-(.+?)-(opus|sonnet|haiku)$`
替换：`claude-$2-$1`

// 步骤 2：标准化版本号
正则：`-(\d+)-(\d+)$`
替换：`-$1.$2`

4. 批量更新

支持选中多个供应商，一键触发模型列表更新。

批量更新模型

支持选项：

自动同意变更：跳过差异确认步骤。
自动重命名：更新后立即应用重命名规则。

健康监控

健康监控模块提供平台、密钥、模型的健康状态管理：

1. 概览视图

展示平台、密钥、模型的健康状态统计，快速了解系统整体健康状况。

2. 问题管理

平台健康：查看各平台的健康状态和错误信息。
密钥健康：监控 API 密钥的可用性。
模型健康：追踪各模型的运行状态。

3. 一键恢复

支持一键恢复异常状态，快速恢复服务。

请求日志

日志模块记录了详细的 API 调用链路信息：

时间戳：请求发起时间。
真实模型：实际处理请求的模型名称。
路由节点：实际处理请求的供应商。
模式：流式 / 非流式。
状态：HTTP 状态码及成功/失败标记。
总耗时：请求完整生命周期耗时。
Token 统计：Prompt / Completion Token 消耗。
TTFT：首字响应时间 (Time To First Token)。
Trace：错误堆栈及详细报错信息。

技术架构

后端技术栈

Go 1.23.8：高性能编程语言
Fiber v2：高性能 Web 框架
GORM：ORM 库
slog：结构化日志

前端技术栈

Vue 3 ^3.5.18：渐进式 JavaScript 框架
TypeScript ~5.8.0：类型安全
Vite (rolldown-vite)：下一代前端构建工具
Naive UI ^2.42.0：Vue 3 组件库
Pinia ^3.0.3：状态管理

Portal 核心依赖

Portal 是拼好 AI 的核心依赖，提供以下关键能力：

三模式 API

模式	入口格式	路由策略	出口格式	适用场景
Contract API	统一格式	默认端点	统一格式	跨平台兼容、统一处理
Native API	原生格式	指定 Provider 端点	原生格式	平台特定功能、无额外开销
Native API + Compat	原生格式	先尝试指定端点，降级到默认端点	原生格式	高可用、渐进式迁移

智能路由

基于模型名称和健康状态自动选择最佳通道
支持随机选择和多维 LRU 选择策略
可自定义扩展选择策略

适配器支持

OpenAI：Chat Completions API 和 Responses API
Gemini：GenerateContent API
Anthropic：Messages API

尾巴

因为拼好 AI 目前其实是还没出到正式版的，基本上是一边用一边修修补补，因此功能和特性估计都不是很稳定，凑合着用吧（x

1760778929595