告别API碎片化：One-API如何用开源方案打通国内外大模型？

它支持多种主流模型，包括 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek，以及国内的字节豆包、ChatGLM、文心一言、讯飞星火、通义千问、360 智脑、腾讯混元等。One-API 是一个开源项目，托管于 GitHub（One-API GitHub），其核心目标是通过标准化的 OpenAI API 格式，为开发者提供一个统一的接口来访问多种

溪源More

148人浏览 · 2025-06-30 08:00:57

溪源More · 2025-06-30 08:00:57 发布

One-API 概述

随着大型语言模型（LLM）的快速发展，开发者面临如何高效管理和调用不同模型提供商 API 的挑战。One-API 是一个开源的 API 管理与分发系统，旨在通过统一的接口解决这一问题。它支持多种主流模型，包括 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek，以及国内的字节豆包、ChatGLM、文心一言、讯飞星火、通义千问、360 智脑、腾讯混元等。本文将深入探讨 One-API 的功能、架构、部署方法、使用方式、集成方法、社区支持等知识点，为读者提供全面的参考。

One-API 是一个开源项目，托管于 GitHub（One-API GitHub），其核心目标是通过标准化的 OpenAI API 格式，为开发者提供一个统一的接口来访问多种 LLM。无论是国外模型还是国内模型，One-API 都能将其整合到一个平台，简化开发流程，提高代码复用性。

核心优势

统一接口：开发者只需学习一套 API 格式，即可调用所有支持的模型。
密钥管理：支持多用户密钥分发，适合团队协作或商业化运营。
灵活部署：提供单可执行文件和 Docker 镜像，部署简单。
扩展性：支持负载均衡和多机部署，适应高并发场景。
开源社区：MIT 许可证，社区活跃，文档和教程丰富。

功能详解

One-API 提供了多项功能，以下是其主要特性：

1. 多模型支持

One-API 支持的模型涵盖国际和国内主流 LLM，提供商包括：

国际模型：OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek。
国内模型：字节豆包、ChatGLM、文心一言、讯飞星火、通义千问、360 智脑、腾讯混元。

模型提供商	代表模型	特点
OpenAI	GPT-4	强大的文本生成能力
Azure	Azure OpenAI	企业级部署支持
百度	文心一言	国内领先的 NLP 模型
讯飞	星火认知	免费 token 供学习使用
阿里	通义千问	高效的中文处理能力

2. 统一 API 接口

One-API 通过模仿 OpenAI 的 API 格式（如 /v1/chat/completions），为所有模型提供一致的请求和响应结构。例如，开发者可以使用相同的请求格式调用 OpenAI 的 GPT-4 或讯飞的星火模型，无需修改代码。

示例请求：

{
  "model": "SparkDesk-v3.5",
  "messages": [
    {
      "role": "user",
      "content": "给我讲个笑话吧。"
    }
  ],
  "temperature": 0.7
}

3. 密钥管理与分发

One-API 允许管理员为不同用户或应用生成访问令牌（token），并设置配额、过期时间、IP 限制等。这种功能特别适合：

企业内部多个团队共享 API 资源。
商业化场景中向客户提供 API 访问服务。

4. 负载均衡

One-API 支持负载均衡，可将请求分配到多个实例或提供商。如果配置了多个相同模型的渠道，系统会根据优先级或随机选择一个渠道处理请求，确保高可用性和性能。

5. 流式传输

流式传输（stream mode）允许实时接收模型的响应，适合需要低延迟的应用，如聊天机器人或实时翻译工具。

6. 部署简便

One-API 提供两种主要部署方式：

单可执行文件：下载预编译的二进制文件，直接运行。
Docker 镜像：通过 Docker 容器快速部署，支持数据持久化。

架构解析

One-API 的架构设计使其能够高效地作为客户端与 LLM 提供商之间的代理层。其主要组件包括：

Web 界面：提供用户管理、渠道配置、令牌生成等功能，默认访问地址为 http://localhost:3000/。
API 服务器：处理客户端的 API 请求，路由到相应的模型提供商。
数据库：支持 SQLite 或其他 SQL 数据库，存储用户数据、令牌、配额等信息。
缓存层：使用 Redis（可选）进行会话管理和缓存。

工作原理

客户端发送标准化的 API 请求到 One-API（如 /v1/chat/completions）。
One-API 验证请求中的令牌，检查配额和权限。
根据请求中的 model 参数，选择对应的模型提供商渠道。
One-API 向提供商发送请求，获取响应后返回给客户端。

这种代理模式屏蔽了不同提供商 API 的差异，同时提供了额外的管理功能。

部署方法

One-API 的部署方式灵活，支持多种环境。以下是主要部署方法的详细说明：

1. Docker 部署

Docker 是推荐的部署方式，因其简单且支持跨平台。以下是部署步骤：

步骤：

拉取镜像：
```
docker pull justsong/one-api
```

运行容器：

docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /path/to/data:/data justsong/one-api

-p 3000:3000：映射端口。
-v /path/to/data:/data：数据持久化。
-e TZ=Asia/Shanghai：设置时区。

访问 http://localhost:3000/，使用默认账号（用户名：root，密码：123456）登录。

注意：

首次登录后需更改默认密码。
数据卷路径需根据操作系统调整（如 Windows 使用 C:/path/to/data）。

2. 手动部署

手动部署适合不使用 Docker 的场景，需下载预编译的二进制文件。

步骤：

从 GitHub 发布页面（Releases）下载适合操作系统的二进制文件（如 Windows 的 .exe）。
运行二进制文件：
```
./one-api --port 3000 --log-dir ./logs
```
访问 http://localhost:3000/ 进行配置。

注意：

需确保运行环境支持 Go 或相关依赖。
手动部署可能需要手动配置数据库和缓存。

3. 第三方平台部署

One-API 支持在 Sealos、Zeabur 等平台上的一键部署。这些平台提供图形化界面，适合不熟悉命令行的用户。

配置指南

部署完成后，需要进行配置以启用模型访问。以下是主要配置步骤：

1. 环境变量

One-API 支持通过环境变量自定义配置，常用变量包括：

SQL_DSN：数据库连接字符串，如 user:password@tcp(host:port)/one-api。
REDIS_CONN_STRING：Redis 连接字符串，用于缓存。
SESSION_SECRET：会话加密密钥。
THEME：界面主题，默认值为 default。

示例：

export SQL_DSN="root:123456@tcp(localhost:3306)/one-api"
export REDIS_CONN_STRING="redis://localhost:6379/0"
docker run -e SQL_DSN -e REDIS_CONN_STRING justsong/one-api

2. 渠道配置

渠道（Channel）是指连接到特定模型提供商的配置。管理员需在 Web 界面中添加渠道。

步骤：

登录 Web 界面，进入“渠道管理”。
添加新渠道，输入提供商的 API 密钥（如讯飞星火的 APPID|APISecret|APIKey）。
指定支持的模型（如 SparkDesk-v3.5）。

3. 令牌管理

管理员可为用户生成访问令牌，设置配额、过期时间等。

示例：

配额：100,000 tokens。
过期时间：30 天。
允许的模型：SparkDesk-v3.5、gpt-4。

使用方式

One-API 提供 Web 界面和 API 两种使用方式。

1. Web 界面

Web 界面是管理的主要入口，功能包括：

用户管理：添加、删除用户，设置权限。
渠道管理：配置模型提供商。
令牌管理：生成和管理访问令牌。
日志查看：监控 API 使用情况。

访问地址：http://localhost:3000/
默认凭据：用户名 root，密码 123456（需首次更改）。

2. API 使用

One-API 的 API 兼容 OpenAI 的格式，常用端点包括：

端点	方法	描述
`/v1/chat/completions`	POST	发起聊天完成请求
`/api/user/self`	GET	获取当前用户信息
`/api/topup`	POST	为用户充值配额

示例请求（使用 cURL）：

curl -X POST http://localhost:3000/v1/chat/completions \
-H "Authorization: Bearer your-token" \
-H "Content-Type: application/json" \
-d '{
  "model": "SparkDesk-v3.5",
  "messages": [{"role": "user", "content": "你好！"}],
  "temperature": 0.7
}'

注意：

令牌需以 Bearer 前缀发送。
模型名称需与渠道配置一致。

3. C# 集成示例

以下是一个使用 C# 调用 One-API 的示例代码：

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

classProgram
{
    privatestaticreadonly HttpClient client = new HttpClient();

    static async Task Main(string[] args)
    {
        string apiUrl = "http://localhost:3000/v1/chat/completions";
        string token = "your-token";
        string jsonPayload = @"{
            ""model"": ""SparkDesk-v3.5"",
            ""messages"": [
                {
                    ""role"": ""user"",
                    ""content"": ""给我讲个笑话吧。""
                }
            ],
            ""temperature"": 0.7
        }";

        client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
        var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

        try
        {
            HttpResponseMessage response = await client.PostAsync(apiUrl, content);
            response.EnsureSuccessStatusCode();
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseBody);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"请求失败: {ex.Message}");
        }
    }
}

此代码通过 HTTP POST 请求调用 One-API 的聊天完成端点，适用于快速集成到 C# 应用中。