Hướng dẫn triển khai và sử dụng One API: Kết nối nhiều mô hình AI lớn qua một OpenAI API thống nhất

One API là gì

One API là một hệ thống quản lý và chuyển tiếp API mô hình ngôn ngữ lớn mã nguồn mở. Hệ thống chuẩn hóa giao diện của các nhà cung cấp mô hình khác nhau về định dạng API OpenAI, cho phép máy khách sử dụng cùng một API Base và mã thông báo truy cập để gọi nhiều kênh thượng nguồn.

Dự án hỗ trợ nhiều dịch vụ như OpenAI và Azure OpenAI, Anthropic Claude, Google Gemini, Mistral, Doubao, Wenxin Yiyan, Tongyi Qianwen, iFlytek Spark, ChatGLM, Tencent Hunyuan, Moonshot AI, DeepSeek, Ollama, Cohere, Groq, Cloudflare Workers AI, xAI và nhiều dịch vụ khác.

Lưu ý tuân thủ: Khi sử dụng One API, bạn phải tuân thủ Điều khoản sử dụng OpenAI và các luật, quy định hiện hành; không được sử dụng cho mục đích bất hợp pháp. Không cung cấp dịch vụ trí tuệ nhân tạo tạo sinh chưa đăng ký cho công chúng tại Trung Quốc.

Tính năng chính

• Giao diện thống nhất: Truy cập các mô hình ngôn ngữ lớn khác nhau thông qua định dạng API tương thích với OpenAI.

• Nhiều kênh và cân bằng tải: Cấu hình nhiều kênh thượng nguồn; khi không chỉ định kênh, hệ thống sẽ tự động cân bằng tải.

• Phản hồi theo luồng: Hỗ trợ chế độ stream để tạo phản hồi kiểu máy đánh chữ.

• Quản lý mã thông báo: Có thể thiết lập thời hạn, hạn mức, phạm vi IP được phép và các mô hình được phép truy cập.

• Quản lý kênh: Hỗ trợ tạo hàng loạt kênh, thiết lập danh sách mô hình, nhóm kênh và ánh xạ mô hình.

• Hạn mức và tính phí: Hỗ trợ chi tiết hạn mức, nhóm người dùng, nhóm kênh, hệ số và hiển thị hạn mức bằng đô la Mỹ.

• Độ tin cậy: Hỗ trợ tự động thử lại khi thất bại, triển khai nhiều máy, bộ nhớ đệm Redis và cấu hình kết nối cơ sở dữ liệu.

• Mở rộng quản trị: Có thể gọi API quản trị bằng mã thông báo truy cập hệ thống để mở rộng khả năng quản trị mà không cần sửa mã nguồn.

• Hệ thống người dùng: Hỗ trợ đăng ký và đăng nhập qua email, Feishu, GitHub, tài khoản công khai WeChat và các phương thức khác.

• Tùy chỉnh giao diện: Có thể tùy chỉnh tên hệ thống, Logo, chân trang, trang chủ, trang giới thiệu và giao diện.

Triển khai nhanh bằng Docker

Chuẩn bị thư mục dữ liệu

SQLite phù hợp để dùng thử nhanh hoặc triển khai với mức đồng thời thấp. Trước tiên, hãy chuẩn bị một thư mục dữ liệu có quyền ghi; cơ sở dữ liệu và nhật ký sẽ được lưu trong thư mục này.

mkdir -p /home/ubuntu/data/one-api

Khởi động One API

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

Cổng ở bên trái trong -p 3000:3000 là cổng của máy chủ, có thể thay đổi tùy nhu cầu. Sau khi khởi động, truy cập http://localhost:3000/.

Tên người dùng ban đầu là root, mật khẩu ban đầu là 123456.

Quan trọng: Sau khi đăng nhập bằng root lần đầu, phải lập tức thay đổi mật khẩu mặc định.

Nếu không thể kéo image từ Docker Hub, có thể thay justsong/one-api bằng ghcr.io/songquanpeng/one-api. Nếu container không khởi động được, có thể thử thêm --privileged=true theo các bản ghi sự cố của dự án.

Triển khai bằng MySQL

Khi lượng truy cập đồng thời lớn, README khuyến nghị thiết lập SQL_DSN và không tiếp tục sử dụng SQLite. Cơ sở dữ liệu oneapi cần được tạo trước, nhưng các bảng sẽ do chương trình tự động tạo.

docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

Hãy thay tên người dùng, mật khẩu, địa chỉ và cổng bằng thông số cơ sở dữ liệu thực tế. Nếu MySQL chạy trên máy chủ, tùy môi trường mạng có thể thêm --network="host" để container truy cập cơ sở dữ liệu trên máy chủ.

Sử dụng Docker Compose

Kho mã cung cấp phương thức khởi động bằng Docker Compose. Hiện tại hướng dẫn sử dụng MySQL và lưu dữ liệu trong thư mục ./data/mysql.

docker-compose up -d
docker-compose ps

Triển khai thủ công từ mã nguồn

Nếu muốn tự xây dựng, hãy chuẩn bị môi trường Node.js, npm và Go, sau đó lần lượt xây dựng frontend và backend.

git clone https://github.com/songquanpeng/one-api.git
cd one-api/web/default
npm install
npm run build

cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

Sau khi xây dựng xong, hãy thêm quyền thực thi và khởi động dịch vụ:

chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

--port dùng để chỉ định cổng lắng nghe, giá trị mặc định là 3000; --log-dir dùng để chỉ định thư mục nhật ký. Bạn cũng có thể dùng --version để xem phiên bản hoặc --help để xem trợ giúp.

Hoàn tất cấu hình cơ bản

1. Mở trang quản trị One API, đăng nhập bằng tài khoản root và thay đổi mật khẩu mặc định.

2. Vào trang Kênh, chọn loại nhà cung cấp tương ứng và thêm API Key thượng nguồn.

3. Thiết lập danh sách mô hình và nhóm mà kênh hỗ trợ theo khả năng của dịch vụ thượng nguồn.

4. Vào trang Mã thông báo và tạo mã thông báo truy cập cho máy khách.

5. Thiết lập hạn mức, thời hạn, phạm vi IP được phép và các mô hình có thể truy cập cho mã thông báo theo nhu cầu.

One API có thể sử dụng ngay sau khi cài đặt. Các cấu hình khác có thể thực hiện thông qua giao diện quản trị, biến môi trường, tệp .env hoặc tham số dòng lệnh. Khi sử dụng .env, hãy tham khảo .env.example trong kho mã và đổi tên thành .env.

Sử dụng qua giao diện tương thích với OpenAI

Máy khách cần đặt API Base thành địa chỉ triển khai One API của bạn và API Key thành mã thông báo One API vừa tạo. Định dạng Base URL cụ thể tùy thuộc vào máy khách; với thư viện chính thức của OpenAI, README đưa ra cấu hình như sau:

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"

Yêu cầu trước tiên sẽ đến One API, sau đó One API chuyển tiếp đến OpenAI, Azure hoặc các kênh mô hình khác. Với các dịch vụ thượng nguồn có định dạng giao diện khác nhau, One API sẽ xử lý việc chuyển đổi nội dung yêu cầu và phản hồi cần thiết cho quá trình chuyển tiếp.

Kết hợp với máy khách hiện có

Hầu hết máy khách hỗ trợ địa chỉ giao diện OpenAI tùy chỉnh đều có thể kết nối. Lấy ChatGPT Next Web làm ví dụ, trước tiên hãy chạy container của máy khách:

docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web

Sau đó điền địa chỉ giao diện One API và mã thông báo One API trên trang máy khách. Cổng cần tránh xung đột với 3000 mà One API đang sử dụng.

ChatGPT Web cũng có thể kết nối với One API thông qua biến môi trường:

docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.example.com -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web

Hãy thay tên miền mẫu và mã thông báo bằng cấu hình của bạn.

Kỹ thuật cấu hình nâng cao

Chỉ định kênh hoặc bật cân bằng tải

Theo mặc định, các yêu cầu không chỉ định kênh sẽ được cân bằng tải giữa nhiều kênh khả dụng. Mã thông báo do quản trị viên tạo cũng có thể nối thêm ID kênh để buộc yêu cầu hiện tại được xử lý bởi một kênh cụ thể:

Authorization: Bearer ONE_API_KEY-CHANNEL_ID

Mã thông báo do người dùng thông thường tạo không thể chỉ định ID kênh theo cách này.

Thận trọng khi sử dụng ánh xạ mô hình

Ánh xạ mô hình có thể chuyển hướng mô hình trong yêu cầu của người dùng sang một mô hình khác. Tuy nhiên, README lưu ý rằng không nên thiết lập ánh xạ mô hình nếu không cần thiết, vì sau khi bật, nội dung yêu cầu sẽ được xây dựng lại thay vì chuyển tiếp trực tiếp; một số trường chưa được hỗ trợ chính thức có thể không được truyền thành công.

Sử dụng bộ nhớ đệm Redis

Sau khi thiết lập REDIS_CONN_STRING, One API sẽ sử dụng Redis làm bộ nhớ đệm:

REDIS_CONN_STRING=redis://default:redispw@localhost:49153

Nếu độ trễ truy cập cơ sở dữ liệu rất thấp thì không cần bật Redis, vì bộ nhớ đệm có thể gây chậm trễ đồng bộ dữ liệu. Ở chế độ Sentinel hoặc cluster, có thể đặt biến này thành danh sách nút, đồng thời kết hợp với REDIS_PASSWORD và REDIS_MASTER_NAME.

Tối ưu kết nối cơ sở dữ liệu

Có thể điều chỉnh kết nối cơ sở dữ liệu bằng các biến môi trường sau:

• SQL_MAX_IDLE_CONNS: số kết nối nhàn rỗi tối đa, mặc định là 100.

• SQL_MAX_OPEN_CONNS: số kết nối mở tối đa, mặc định là 1000.

• SQL_CONN_MAX_LIFETIME: thời gian tồn tại tối đa của kết nối, mặc định là 60 phút.

• BATCH_UPDATE_ENABLED=true: bật gộp cập nhật hàng loạt cơ sở dữ liệu, có thể giảm tình trạng quá nhiều kết nối nhưng sẽ gây trễ cập nhật hạn mức.

• BATCH_UPDATE_INTERVAL=5: thiết lập khoảng thời gian gộp cập nhật hàng loạt, tính bằng giây.

Nếu xuất hiện Error 1040: Too many connections, nên giảm thích hợp SQL_MAX_OPEN_CONNS; đồng thời có thể đánh giá việc bật cập nhật hàng loạt.

Cấu hình phiên, thời gian chờ và proxy

• SESSION_SECRET: thiết lập khóa phiên cố định để Cookie của người dùng đã đăng nhập vẫn có hiệu lực sau khi khởi động lại.

• RELAY_TIMEOUT: thiết lập thời gian chờ yêu cầu chuyển tiếp, tính bằng giây.

• RELAY_PROXY: cho phép yêu cầu chuyển tiếp truy cập API thượng nguồn thông qua proxy được chỉ định.

• USER_CONTENT_REQUEST_TIMEOUT: thiết lập thời gian chờ tải nội dung do người dùng tải lên.

• USER_CONTENT_REQUEST_PROXY: cấu hình proxy tải xuống cho hình ảnh và các nội dung khác do người dùng tải lên.

Cấu hình giám sát kênh

Có thể định kỳ cập nhật số dư kênh và kiểm tra khả năng hoạt động của kênh:

CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVAL=5

Đơn vị của hai biến đầu tiên là phút, còn đơn vị của POLLING_INTERVAL là giây, dùng để kiểm soát khoảng thời gian giữa các yêu cầu khi thực hiện thao tác hàng loạt.

Cấu hình triển khai trên nhiều máy

Triển khai trên nhiều máy không thể tiếp tục phụ thuộc vào SQLite cục bộ. Tất cả các nút phải kết nối đến cùng một cơ sở dữ liệu MySQL và duy trì cấu hình phiên nhất quán.

1. Đặt SESSION_SECRET giống nhau trên tất cả máy chủ.

2. Tất cả máy chủ kết nối đến cùng một cơ sở dữ liệu MySQL thông qua SQL_DSN.

3. Đặt NODE_TYPE=slave trên máy chủ phụ; nếu không thiết lập, máy chủ sẽ mặc định là máy chủ chính.

4. Sử dụng SYNC_FREQUENCY để đồng bộ cấu hình định kỳ từ cơ sở dữ liệu.

5. Máy chủ phụ có thể đặt FRONTEND_BASE_URL để chuyển hướng các yêu cầu trang đến máy chủ chính.

6. Có thể triển khai Redis trên từng máy chủ phụ và đặt REDIS_CONN_STRING để giảm số lần truy cập cơ sở dữ liệu trong thời gian bộ nhớ đệm còn hiệu lực.

7. Nếu độ trễ truy cập cơ sở dữ liệu của máy chủ chính cao, cũng nên cân nhắc bật Redis và đồng bộ định kỳ.

SESSION_SECRET=random_string
SQL_DSN=root:123456@tcp(database:3306)/oneapi
NODE_TYPE=slave
SYNC_FREQUENCY=60
FRONTEND_BASE_URL=https://openai.example.com
REDIS_CONN_STRING=redis://default:redispw@localhost:49153

Cấu hình Nginx và HTTPS

Trong môi trường production, có thể sử dụng Nginx làm proxy ngược cho One API. Đối với các mô hình có thời gian phản hồi dài, nên tăng thời gian chờ đọc một cách phù hợp.

server {
    server_name openai.example.com;

    location / {
        client_max_body_size 64m;
        proxy_http_version 1.1;
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header Accept-Encoding gzip;
        proxy_read_timeout 300s;
    }
}

Trên Ubuntu, có thể sử dụng Certbot để yêu cầu và cấu hình HTTPS:

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart

Khắc phục các sự cố thường gặp

• Hiển thị thông báo không đủ hạn mức: Ngoài hạn mức tài khoản, cũng cần kiểm tra giới hạn hạn mức của chính token.

• Hiển thị thông báo không có kênh khả dụng: Kiểm tra nhóm người dùng, nhóm kênh và danh sách mô hình mà kênh hỗ trợ.

• Tải của nhóm hiện tại đã bão hòa: Thông thường có nghĩa là kênh upstream đã trả về 429.

• Máy khách hiển thị Failed to fetch: Kiểm tra địa chỉ API, API Key và cấu hình HTTPS; các yêu cầu HTTP trên trang HTTPS có thể bị trình duyệt chặn.

• Kiểm tra kênh trả về invalid character: Phản hồi từ upstream có thể là HTML thay vì JSON hợp lệ; IP của máy chủ triển khai hoặc nút proxy cũng có thể bị Cloudflare chặn.

• Lo ngại mất dữ liệu sau khi nâng cấp: Dữ liệu MySQL sẽ không bị mất trong quá trình nâng cấp bình thường; với SQLite, phải gắn kết volume dữ liệu đúng cách để duy trì one-api.db.

Lời kết

One API phù hợp để hợp nhất nhiều nhà cung cấp mô hình vào phương thức gọi tương thích với OpenAI, đồng thời quản lý tập trung các kênh, token, hạn mức và người dùng. Với các tình huống cá nhân hoặc có mức đồng thời thấp, có thể bắt đầu bằng Docker và SQLite; môi trường có mức đồng thời cao và triển khai trên nhiều máy nên sử dụng cơ sở dữ liệu dùng chung, đồng thời cân nhắc thận trọng việc đưa Redis vào sử dụng dựa trên tình hình độ trễ. Trước khi đưa vào vận hành, hãy thay đổi mật khẩu mặc định, cấu hình HTTPS, duy trì dữ liệu và bảo đảm dịch vụ tuân thủ các điều khoản cũng như quy định pháp luật liên quan.

Dự án được phát hành nguồn mở theo giấy phép MIT, nhưng README yêu cầu giữ lại thông tin ghi công và liên kết dự án ở cuối trang; nếu cần xóa thông tin ghi công, phải được cấp phép trước. Xem thêm thông tin tại kho lưu trữ One API trên GitHub.