Cherry Studio
Cấu hình và sử dụng AGTCloud trong Cherry Studio.
Cherry Studio là ứng dụng máy tính hỗ trợ nhiều mô hình trên Windows, macOS và Linux. Thêm nhà cung cấp OpenAI tùy chỉnh để dùng điểm vào tương thích Chat Completions của AGTCloud.
Hướng dẫn này chỉ trình bày kết nối trò chuyện thông thường. Tệp, hình ảnh, gọi công cụ, suy luận, cơ sở tri thức, Agent, MCP và khả năng nâng cao khác phụ thuộc phiên bản Cherry Studio cùng phạm vi hỗ trợ thực tế của mô hình đích.
Chuẩn bị
Trước khi bắt đầu, hãy đảm bảo bạn đã:
- Chuẩn bị thiết bị Windows, macOS hoặc Linux được hỗ trợ;
- Đăng ký và đăng nhập AGTCloud;
- Tạo AGTCloud API Key trên trang API Keys;
- Sao chép ID mô hình mà API Key hiện tại nhìn thấy và hỗ trợ Chat Completions từ danh mục mô hình.
Tải và cài đặt Cherry Studio
Tải gói cài đặt từ trang tải chính thức Cherry Studio. Trang tải và tên gói có thể thay đổi theo phiên bản; chọn bản hiện tại phù hợp với hệ điều hành và kiến trúc bộ xử lý.
- Máy Intel hoặc AMD thông thường dùng bản cài đặt Windows x64;
- Thiết bị Windows ARM dùng gói ARM64;
- Sau khi tải, chạy trình cài đặt và làm theo hướng dẫn giao diện.
Nếu chưa rõ kiến trúc thiết bị, xem System type trong Settings → System → About.
Sau khi cài, khởi chạy Cherry Studio. Nếu lần đầu có lời nhắc khởi tạo, thư mục dữ liệu hoặc cập nhật, hoàn tất theo giao diện phiên bản hiện tại.
Thêm nhà cung cấp AGTCloud
Mở cài đặt dịch vụ mô hình
Mở Cherry Studio và vào Settings → Model Provider. Trong giao diện tiếng Trung, mục này có tên tương ứng là cài đặt và dịch vụ mô hình.
Thêm nhà cung cấp tùy chỉnh
Nhấn Add hoặc nút thêm trong danh sách để tạo nhà cung cấp tùy chỉnh. Điền AGTCloud cho Provider Name và chọn OpenAI cho Provider Type.
Điền thông tin kết nối
| Trường Cherry Studio | Giá trị |
|---|---|
Provider Name | AGTCloud |
Provider Type | OpenAI |
Chat Endpoint / Protocol (nếu có) | OpenAI Chat Completions |
API Key | your-api-key |
API Host | https://api.agtcloud.cn/v1/ |
Custom Headers | Để trống theo mặc định |
Thay your-api-key bằng AGTCloud API Key đã tạo trên trang API Keys. Nếu phiên bản hiện tại cho phép chọn giao thức trò chuyện, dùng OpenAI Chat Completions.
Bật nhà cung cấp
Sau khi lưu, bật công tắc ở góc trên bên phải nhà cung cấp. Khi nhà cung cấp chưa bật, mô hình đã thêm cũng không xuất hiện trong danh sách của trang trò chuyện.
API Host cần kết thúc bằng /
Điền https://api.agtcloud.cn/v1/. Không điền địa chỉ yêu cầu /v1/chat/completions đầy đủ, vì Cherry Studio có thể nối đường dẫn lần nữa và tạo Endpoint lặp.
Lấy và thêm mô hình
Mở quản lý mô hình
Nhấn Manage trên trang cấu hình nhà cung cấp AGTCloud. Cherry Studio thử lấy các mô hình hiển thị theo API Host và API Key hiện tại.
Thêm mô hình vào danh sách
Tìm mô hình hỗ trợ Chat Completions trong danh sách trả về và nhấn + bên phải. Chỉ mô hình được thêm vào danh sách của nhà cung cấp mới xuất hiện trong bộ chọn trên trang trò chuyện.
Thêm thủ công khi không tải được
Nếu danh sách không tải bình thường, kiểm tra API Host, API Key và trạng thái bật nhà cung cấp trước. Bạn cũng có thể sao chép ID mô hình từ danh mục mô hình, rồi điền MODEL_ID qua mục thêm thủ công của phiên bản Cherry Studio hiện tại.
Kiểm tra kết nối
Nhấn nút kiểm tra kết nối gần ô nhập API Key. Cherry Studio thường dùng mô hình trò chuyện cuối cùng trong danh sách đã thêm để kiểm tra; nếu thất bại, xác nhận danh sách có ít nhất một mô hình trò chuyện mà API Key hiện tại có thể gọi.
Cấu hình mô hình theo khả năng thực tế
Không cần thêm tất cả mô hình cùng lúc. Độ dài ngữ cảnh, đầu vào tệp, hiểu hình ảnh, gọi công cụ và suy luận phụ thuộc phạm vi hỗ trợ thực tế của mô hình và điểm vào giao thức hiện tại.
Bắt đầu hội thoại đầu tiên
Tạo chủ đề mới
Quay lại trang trò chuyện Cherry Studio và tạo chủ đề mới.
Chọn mô hình AGTCloud
Mở bộ chọn mô hình và chọn AGTCloud → MODEL_ID. MODEL_ID là giá trị giữ chỗ; giao diện thực tế hiển thị ID mô hình bạn vừa thêm.
Kiểm tra kết quả
Nếu máy khách nhận trả lời bình thường, API Host, API Key và mô hình đã kết nối cơ bản. Bước này phát sinh mức sử dụng API thông thường.
Câu hỏi thường gặp
| Hiện tượng | Kiểm tra trước | Cách xử lý |
|---|---|---|
| Mô hình AGTCloud không hiển thị | Công tắc nhà cung cấp và trạng thái thêm mô hình | Bật nhà cung cấp, xác nhận mô hình đích đã được thêm vào danh sách của nhà cung cấp |
Manage trả danh sách trống | API Host, API Key và phạm vi mô hình của tài khoản | Điền lại API Host và API Key hoặc sao chép MODEL_ID từ danh mục mô hình rồi thêm thủ công |
| Kiểm tra kết nối thất bại | Mô hình đã thêm, giao thức và quyền Key | Đảm bảo mô hình trò chuyện cuối cùng trong danh sách có thể được Key hiện tại gọi qua Chat Completions |
Trả về 401 | Nội dung API Key và trạng thái token | Sao chép API Key hợp lệ, xác nhận không có khoảng trắng thừa |
Trả về 403 | Quyền token, quyền mô hình và trạng thái tài khoản | Kiểm tra trạng thái API Key và phạm vi mô hình của tài khoản trong bảng điều khiển |
Trả về 404 | API Host, đường dẫn lặp và ID mô hình | Dùng https://api.agtcloud.cn/v1/, không điền Endpoint đầy đủ và kiểm tra lại ID mô hình |
| Đường dẫn yêu cầu bị lặp | API Host chứa địa chỉ yêu cầu đầy đủ | Khôi phục https://api.agtcloud.cn/v1/ kết thúc bằng /, rồi kiểm tra lại kết nối |
| Gọi tính năng nâng cao thất bại | Khả năng thực tế, hỗ trợ giao thức và phiên bản máy khách | Tắt tính năng tệp, công cụ, cơ sở tri thức hoặc suy luận trước, rồi kiểm tra bằng văn bản thông thường |
| Trả lời ngắt hoặc chậm | Proxy mạng, độ dài ngữ cảnh và trạng thái mô hình | Thử lại với chủ đề mới ngắn hơn, kiểm tra mạng cục bộ và trạng thái mô hình hiện tại |
Nếu chưa xác định được vấn đề, ghi lại thời gian yêu cầu, ID mô hình, trạng thái HTTP và lỗi đã loại thông tin nhạy cảm, rồi xem Lỗi và khắc phục sự cố. Không gửi API Key đầy đủ.
Khuyến nghị bảo mật
- Không đưa API Key vào ảnh chụp màn hình, bản xuất hội thoại, nhật ký hoặc cấu hình dùng chung;
- Không gửi mật khẩu, dữ liệu khách hàng, tệp riêng tư hoặc nội dung nhạy cảm khác trong lần kiểm tra đầu;
- Trên thiết bị dùng chung, xóa thông tin xác thực đã lưu trong Cherry Studio sau khi dùng;
- Trước khi xuất hoặc chia sẻ cấu hình Cherry Studio, xác nhận không chứa API Key.