Hướng dẫn tích hợp Windsurf: Cấu hình endpoint tùy chỉnh cho tác nhân Cascade
Hướng dẫn tích hợp Codeium Windsurf AI IDE: Cấu hình endpoint mô hình tùy chỉnh và API Key trong cài đặt để gọi các mô hình Claude / GPT / Gemini.
I. Windsurf là gì?
Windsurf là IDE ưu tiên AI, tích hợp sẵn tác nhân Cascade và hỗ trợ thêm các điểm cuối (endpoint) mô hình tùy chỉnh. Bằng cách trỏ nó đến cổng kết nối (gateway) của chúng tôi, bạn có thể gọi Claude / GPT / Gemini bằng một khóa API thống nhất.
II. Công tác chuẩn bị
- Đăng nhập vào bảng điều khiển API Jizhi, tạo API Key
sk-xxxxxx(chỉ hiển thị một lần, vui lòng lưu lại). - Xác nhận slug của mô hình bạn muốn sử dụng (ví dụ:
claude-sonnet-5,gpt-5.5,gemini-3.7-flash). - Xác nhận địa chỉ cổng kết nối:
https://www.relay-api.com.
III. Cấu hình trong Windsurf
Mở Settings → Models / API Providers → Add Provider, sau khi chọn loại nhà cung cấp, hãy điền thông tin sau:
Base URL : https://www.relay-api.com # Claude / Anthropic
API Key : sk-khóa_của_bạn
Model : claude-sonnet-5
(Đối với mô hình GPT, hãy đổi Base URL thành https://www.relay-api.com/v1)
(Đối với mô hình Gemini, hãy đổi Base URL thành https://www.relay-api.com/v1beta)Sau khi lưu, hãy chọn mô hình đó trong Cascade và sử dụng Ctrl+L (trên macOS là Cmd+L) để bắt đầu cuộc trò chuyện.
IV. Đối chiếu địa chỉ giao diện
| Nhóm mô hình | Cổng vào (Base URL) | Giao thức |
|---|---|---|
| Claude / Anthropic | https://www.relay-api.com | Anthropic Messages |
| GPT / OpenAI | https://www.relay-api.com/v1 | OpenAI Chat Completions |
| Gemini | https://www.relay-api.com/v1beta | Google generateContent |
Hãy sử dụng địa chỉ cổng vào trong bảng trên cho Base URL.
V. Xử lý sự cố thường gặp
| Hiện tượng | Xử lý |
|---|---|
| 401 / 403 | Khóa không hợp lệ, chưa kích hoạt hoặc không đủ số dư; hãy kiểm tra lại sk- và nạp tiền. |
| 404 / Mô hình không khả dụng | Tên mô hình không khớp với slug trên nền tảng hoặc mô hình chưa được kích hoạt; hãy kiểm tra lại ID mô hình. |
Khuyến nghị bảo mật: Không để lộ khóa API trong các kho lưu trữ công khai; nên tạo các khóa riêng biệt cho các mục đích sử dụng khác nhau để dễ dàng thống kê và giới hạn hạn mức.
Giải thích về Base URL: Hệ thống của chúng tôi chấp nhận cả /v1beta/models/... và /v1beta/v1beta/models/... (cũng như /v1/... và /v1/v1/...), do đó việc ứng dụng khách có tự động thêm /v1 hay /v1beta hay không đều không ảnh hưởng đến quá trình gọi: Bạn có thể điền Base URL là tên miền gốc hoặc địa chỉ có kèm /v1beta đều được. Vui lòng truy cập trang "Token" trong bảng điều khiển, nhấn vào "Model ID" ở góc trên bên phải để tra cứu và sao chép ID mô hình.