Hướng dẫn nhập môn Agent2API: Kết nối trạng thái đăng nhập AI trên máy tính với cổng tương thích OpenAI

Agent2API là gì

Agent2API là một cổng API AI cục bộ, dùng để tích hợp các tài khoản đã đăng nhập trong nhiều ứng dụng máy tính AI và cung cấp khả năng gọi mô hình qua một giao diện tương thích với OpenAI thống nhất. Chỉ cần ứng dụng hỗ trợ tùy chỉnh base_url, bạn có thể kết nối tới http://127.0.0.1:3065/v1, thường không cần API Key của nhà cung cấp và cũng không cần sửa đổi ứng dụng.

Dự án hỗ trợ ba giao thức Chat, Responses và Messages, đồng thời cung cấp giao diện danh sách mô hình /v1/models. Cổng chạy trên máy tính cục bộ hoặc máy chủ bạn triển khai; hạn mức tài khoản vẫn đến từ chính tài khoản tương ứng.

Tổng quan các tính năng chính

• Giao diện tương thích với OpenAI: hỗ trợ /v1/chat/completions, /v1/responses, /v1/messages; Messages cũng hỗ trợ count_tokens.
• Nhiều nhà cung cấp: tích hợp nhiều nhà cung cấp như WorkBuddy, 小浣熊, CatPaw, Qoder, Trae và cho phép cấu hình nhà cung cấp tùy chỉnh.
• Luân phiên tài khoản: tài khoản được xếp hàng theo mức ưu tiên; khi gặp 429 có thể chuyển đổi tài khoản, còn tài khoản đang trong thời gian chờ do giới hạn sẽ không tiếp tục được sử dụng.
• Bảo trì thông tin xác thực: một số nhà cung cấp hỗ trợ tự động gia hạn Token, làm mới hàng loạt thông tin xác thực sắp hết hạn và làm mới danh mục mô hình.
• Mạng và bảo mật: hỗ trợ thiết lập proxy truy cập mạng riêng cho từng tài khoản và phân quyền thông qua nhiều Gateway Key.
• Quản lý vận hành: cung cấp báo cáo về số lượng yêu cầu, tỷ lệ thành công, mức tiêu thụ Token, tỷ lệ trúng bộ nhớ đệm và biểu đồ nhiệt dài hạn.
• Tác vụ định kỳ: có thể quản lý các tác vụ tự động điểm danh, bảo trì thông tin xác thực và làm mới danh mục mô hình.

Chọn phương thức triển khai

Agent2API cung cấp ba hình thức. Bản máy tính phù hợp cho máy tính cá nhân, hỗ trợ Windows, macOS và Linux, đồng thời có thể chạy thường trú trong khay hệ thống; bản máy chủ phù hợp với môi trường Windows Server hoặc Linux không có giao diện đồ họa; Docker phù hợp với người dùng đã có môi trường container. Cả ba phương thức đều không yêu cầu cài Node.js trong thời gian chạy.

• Bản máy tính: khởi động ứng dụng bằng gói cài đặt, cổng chạy trong tiến trình ứng dụng.
• Bản máy chủ: cài đặt dưới dạng dịch vụ hệ thống, truy cập bảng điều khiển quản trị qua trình duyệt và hỗ trợ tự khởi động cùng hệ thống.
• Docker: sử dụng image aimodcc/agent2api:latest, hỗ trợ amd64 và arm64.

Cài đặt và cấu hình lần đầu

Cách một: Bản máy tính

Tải gói cài đặt phù hợp với hệ thống từ Latest Releases của dự án. Sau khi khởi động, vào trang “Tài khoản” và thêm một hoặc nhiều tài khoản nhà cung cấp. Cổng trên bản máy tính mặc định lắng nghe cổng 3065 của máy cục bộ.

Cách hai: Máy chủ Linux

tar -xzf agent2api-server-linux-amd64.tar.gz && cd agent2api-server-linux-amd64 && sudo bash install.sh

Sau khi cài đặt hoàn tất, truy cập http://127.0.0.1:3065/ bằng trình duyệt. Nếu dịch vụ chạy trên máy chủ từ xa, hãy thay tên máy chủ trong địa chỉ bằng IP hoặc tên miền của máy chủ.

Cách ba: Windows Server

Expand-Archive agent2api-server-windows-amd64.zip -DestinationPath C:\agent2api-pkg
cd C:\agent2api-pkg
.\install-service.ps1

Hãy thực thi các lệnh trên trong PowerShell với quyền quản trị viên. Tập lệnh cài đặt sẽ đăng ký dịch vụ vào hệ thống.

Cách bốn: Docker

docker run -d --name agent2api --restart unless-stopped -p 3065:3065 -v ./data:/data aimodcc/agent2api:latest

./data:/data dùng để lưu bền vững cấu hình và dữ liệu tài khoản. Sau khi container khởi động, mở http://127.0.0.1:3065/ để hoàn tất khởi tạo.

Khởi tạo quản trị viên và Gateway Key

1. Mở bảng điều khiển quản trị và đăng ký tài khoản quản trị viên.
2. Vào trang “Gateway Key” và tạo một Key dùng cho ứng dụng gọi API.
3. Vào trang “Tài khoản”, chọn nhà cung cấp và phiên bản, sau đó hoàn tất đăng nhập qua web hoặc nhập trạng thái đăng nhập theo quy trình trên trang.
4. Xác nhận trạng thái tài khoản, thời hạn và thông tin số dư đều bình thường.
5. Vào trang “Quản lý mô hình” để kiểm tra các mô hình khả dụng và ánh xạ mô hình.

Nếu chưa cấu hình Gateway Key, dự án mặc định từ chối yêu cầu API. Không đưa Gateway Key vào mã nguồn công khai, nhật ký hoặc ứng dụng không đáng tin cậy.

Cấu hình tài khoản và mô hình

Trong trang quản lý tài khoản, bạn có thể xem thời hạn tài khoản, số dư, hàng đợi toàn cục và trạng thái chờ do giới hạn theo mô hình. Sau khi thêm nhiều tài khoản, hệ thống sẽ điều phối theo mức ưu tiên; khi một tài khoản gặp 429 hoặc chuyển sang trạng thái chờ, hệ thống có thể chuyển sang tài khoản khả dụng khác.

Trang quản lý mô hình cho phép xem danh sách mô hình, hệ số, thông tin ngữ cảnh và quan hệ ánh xạ theo nhà cung cấp. Danh sách mô hình của các nhà cung cấp hỗ trợ lấy trực tuyến tự động sẽ được làm mới định kỳ; một số nền tảng cũng cung cấp bảng tĩnh tích hợp để dự phòng.

Lần gọi API đầu tiên

Trong ứng dụng hỗ trợ tùy chỉnh địa chỉ API, đặt Base URL thành:

http://127.0.0.1:3065/v1

Nhập Gateway Key vừa tạo vào API Key. Ví dụ có thể dùng sk-local làm giá trị minh họa, nhưng khi gọi thực tế cần sử dụng Key được tạo trong bảng điều khiển.

Trước tiên, kiểm tra trạng thái hoạt động của cổng:

curl http://127.0.0.1:3065/health

Sau đó xem danh sách mô hình:

curl http://127.0.0.1:3065/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

Ví dụ gọi giao diện Chat Completions:

curl http://127.0.0.1:3065/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "Xin chào, hãy giới thiệu về bạn."}
    ]
  }'

Thay YOUR_GATEWAY_KEY bằng Gateway Key và thay YOUR_MODEL_ID bằng ID mô hình do /v1/models trả về. Giao thức Responses và Messages cũng sử dụng cùng địa chỉ Gateway; các trường yêu cầu cụ thể phải tuân theo định dạng của ứng dụng hoặc giao thức tương ứng.

Nhiều tài khoản, proxy và tác vụ định kỳ

Luân phiên nhiều tài khoản

Sau khi thêm nhiều tài khoản cho cùng một nhà cung cấp, có thể tận dụng hàng đợi ưu tiên toàn cục và cơ chế hạ cấp khi gặp 429 để cải thiện tính khả dụng. Nên thiết lập mức ưu tiên hợp lý dựa trên hạn mức, thời hạn và tình huống sử dụng của tài khoản, đồng thời thường xuyên kiểm tra các tài khoản đang chờ.

Proxy truy cập mạng

Dự án hỗ trợ cấu hình cổng ra riêng cho từng tài khoản. Tính năng này phù hợp với các tình huống cần quản lý mạng đi riêng cho từng tài khoản, nhưng người dùng vẫn cần tự đánh giá khả năng hoạt động, tính tuân thủ và rủi ro kiểm soát tài khoản của proxy.

Tác vụ định kỳ

Trong trang quản lý tác vụ, có thể quản lý tập trung việc tự động điểm danh, bảo trì thông tin xác thực và làm mới danh mục mô hình, đồng thời thiết lập công tắc tác vụ và khoảng thời gian thực thi. Lưu ý rằng khả năng hỗ trợ khác nhau tùy nhà cung cấp; ví dụ, một số nền tảng không hỗ trợ gia hạn Token, điểm danh hoặc truy vấn số dư.

Xem báo cáo và mức sử dụng

Trang báo cáo cho phép xem số lượng yêu cầu, tỷ lệ thành công, tổng số Token, mô hình phổ biến và xếp hạng tài khoản, đồng thời xem phân bổ mức sử dụng theo nhà cung cấp. Trang xu hướng hiển thị tỷ lệ trúng bộ nhớ đệm trong 24 giờ, mức tiêu thụ Token và dữ liệu thống kê theo ngày.

Nếu nhà cung cấp hỗ trợ truy vấn số dư hoặc mức sử dụng, bạn cũng có thể xem trực tiếp thông tin tương ứng trên trang tài khoản. Trung tâm điểm danh dùng để xem tổng quan điểm danh và các nhóm điểm danh hằng ngày.

Lưu ý về phát triển và xây dựng

Nếu cần xây dựng bản máy tính từ mã nguồn, yêu cầu môi trường gồm Rust 1.77 trở lên, bộ công cụ Tauri 2 và Node.js 18.17 trở lên. Node.js chỉ được dùng cho việc xây dựng frontend và các tập lệnh Tauri; bản máy tính sau khi đóng gói không phụ thuộc vào Node.js khi chạy.

npm run tauri:install
npm run tauri:dev
npm run tauri:build
npm run build:icon

Trong đó, tauri:dev dùng cho chế độ phát triển và tải lại nóng, còn tauri:build dùng để xây dựng gói cài đặt cho máy tính. DMG của macOS chỉ có thể được xây dựng trên macOS, không thể biên dịch chéo từ Windows; các bản phát hành chính thức được tạo bởi quy trình CI của dự án.

Bảo mật thông tin xác thực và phạm vi sử dụng

Agent2API chỉ dành cho mục đích học tập và trao đổi. Công cụ này sử dụng trạng thái đăng nhập tài khoản của chính bạn dưới dạng ứng dụng khách không chính thức, có thể không phù hợp với điều khoản sử dụng của dịch vụ nguồn. Người dùng tự chịu mọi rủi ro như tài khoản bị giới hạn tốc độ, đưa vào diện kiểm soát rủi ro, đóng băng hoặc cấm.

Dự án sẽ lưu các thông tin xác thực tài khoản như accessToken và refreshToken dưới dạng văn bản thuần trong thư mục cấu hình cục bộ, vị trí mặc định là ~/.agent2api/. Các tệp được xuất cũng có thể chứa thông tin xác thực dạng văn bản thuần, vì vậy không được提交 cấu hình lên kho lưu trữ công khai, tải lên dịch vụ lưu trữ đám mây hoặc chia sẻ với người khác.

README nghiêm cấm sử dụng dự án cho mục đích thương mại, phân phối lại để kiếm lợi, vận hành hàng loạt tài khoản, vượt qua giới hạn thanh toán hoặc hạn ngạch của dịch vụ nguồn, cũng như các hoạt động khác vi phạm pháp luật và quy định. Trong môi trường sản xuất hoặc thương mại, nên sử dụng các kênh chính thức và API chính thức của dịch vụ nguồn. Trước khi sử dụng, hãy đọc LICENSE và tuyên bố sử dụng của dự án.

Lời kết

Agent2API hợp nhất tài khoản của nhiều ứng dụng khách máy tính vào một cổng tương thích với OpenAI chạy cục bộ. Sau khi hoàn tất triển khai, thêm tài khoản và tạo Key cho cổng, bạn có thể sử dụng base_url thống nhất để kết nối với các công cụ hỗ trợ địa chỉ API tùy chỉnh; tính năng xoay vòng nhiều tài khoản, quản lý mô hình, proxy, tác vụ định kỳ và báo cáo phù hợp với các nhu cầu quản lý cục bộ nâng cao hơn. Khi sử dụng, hãy bảo vệ thông tin xác thực cẩn thận và nghiêm túc tuân thủ điều khoản của dịch vụ nguồn cũng như tuyên bố sử dụng bổ sung của dự án.