Hướng dẫn kết nối Hajiyun API và xử lý các lỗi thường gặp

Introduction

Bạn có biết rằng việc cấu hình sai Base URL hoặc nhập sai mã mô hình là những nguyên nhân hàng đầu khiến kết nối API thất bại ngay lần thử đầu tiên? Tài liệu vận hành này được cung cấp bởi đội ngũ Hajiyun nhằm giúp bạn từng bước thiết lập kết nối chính xác và tự khắc phục nhanh chóng các lỗi thường gặp.

Giới thiệu Hajiyun API và Chuẩn bị

Hajiyun là nền tảng cổng API dành cho phát triển phần mềm, dịch thuật, ứng dụng trò chuyện và quy trình làm việc với trí tuệ nhân tạo (AI). Dịch vụ cung cấp website đa ngôn ngữ tại Hajiyun và trang hỗ trợ tiếng Việt tại Hajiyun Tiếng Việt.

Điểm truy cập của Hajiyun tương thích với định dạng OpenAI Chat Completions. Tuy nhiên, khả năng sử dụng thực tế sẽ phụ thuộc vào mô hình được chọn và ứng dụng kết nối của bạn. Việc hỗ trợ Chat Completions không đồng nghĩa với việc hỗ trợ mọi API hoặc mọi tính năng của một ứng dụng cụ thể.

Các bước chuẩn bị trước khi gửi yêu cầu:

API key: Lấy trực tiếp từ trang quản lý tài khoản Hajiyun cá nhân.

Mã mô hình chính xác: Đảm bảo mã mô hình đang khả dụng cho tài khoản của bạn.

Ứng dụng tương thích: Sử dụng ứng dụng hỗ trợ OpenAI Chat Completions và cho phép tùy chỉnh Base URL.

Thông tin tài khoản: Nắm rõ thông tin giá và giới hạn sử dụng hiện hành.

Quy tắc cấu hình Base URL:

Nhập đúng địa chỉ sau nếu ứng dụng yêu cầu Base URL: https://hajiyun.top/v1

Chỉ sử dụng địa chỉ sau khi ứng dụng yêu cầu rõ ràng URL đầy đủ của endpoint Chat Completions: https://hajiyun.top/v1/chat/completions

Lưu ý cực kỳ quan trọng: Không nhập lặp lại phần đường dẫn mà ứng dụng kết nối của bạn đã tự động thêm vào phía sau.

Hình ảnh tóm tắt các thành phần cần chuẩn bị trước khi kết nối và quy tắc nhập Base URL để tránh lỗi trùng lặp đường dẫn.

Quy trình thử kết nối lần đầu

Để đảm bảo hệ thống hoạt động ổn định và tránh các lỗi cấu hình cơ bản, hãy thực hiện quy trình thử nghiệm kết nối đầu tiên theo 5 bước tiêu chuẩn sau:

Kiểm tra thông tin: Xem danh sách mô hình và bảng giá hiện hành trong tài khoản của bạn.

Lấy API key: Sao chép khóa bảo mật từ trang quản lý.

Điền cấu hình: Nhập chính xác Base URL, API key và mã mô hình vào ứng dụng của bạn.

Gửi yêu cầu thử nghiệm: Gửi một câu hỏi ngắn, đơn giản và tuyệt đối không chứa dữ liệu nhạy cảm hoặc thông tin cá nhân.

Xác nhận kết quả: Kiểm tra câu trả lời hiển thị trên ứng dụng và mức độ sử dụng tài nguyên được ghi nhận trên hệ thống.

Lưu ý: Chỉ sau khi yêu cầu văn bản đơn giản hoạt động ổn định, bạn mới nên thử nghiệm tiếp các tính năng nâng cao như streaming (phản hồi dạng dòng), đầu vào bằng hình ảnh hoặc gọi công cụ (tool calling) - nếu mô hình và dịch vụ có hỗ trợ.

Trình chiếu hướng dẫn từng bước kiểm tra tài khoản, lấy key, điền cấu hình và gửi yêu cầu thử nghiệm ban đầu.

Xử lý lỗi Xác thực (401) và Quyền truy cập (403)

Khi gặp sự cố trong quá trình gửi yêu cầu, hệ thống sẽ trả về các mã lỗi tiêu chuẩn. Dưới đây là cách xử lý hai lỗi bảo mật phổ biến:

Lỗi 401: Kiểm tra xác thực

Lỗi này xuất hiện khi thông tin định danh không được hệ thống chấp nhận. Hãy rà soát kỹ các yếu tố sau:

API key có được sao chép đầy đủ hay không.

Có khoảng trắng hoặc ký tự lạ thừa thãi nào dính vào chuỗi key hay không.

Key còn hiệu lực hoạt động hay không.

Ứng dụng kết nối có đang gửi yêu cầu tới đúng địa chỉ dịch vụ của Hajiyun hay không.

Nếu bạn tự viết mã (code), hãy kiểm tra lại cấu trúc gửi thông tin xác thực (header) đúng theo tài liệu hướng dẫn API.

Cảnh báo an toàn: Tuyệt đối không đăng tải công khai API key lên các diễn đàn, nhóm hỗ trợ công cộng để nhờ kiểm tra lỗi.

Lỗi 403: Kiểm tra quyền truy cập

Lỗi 403 thường liên quan đến quyền của tài khoản, quyền sử dụng một mô hình cụ thể hoặc chính sách truy cập hệ thống.

Đọc kỹ nội dung phản hồi: Hãy luôn đọc nội dung chi tiết đi kèm thông báo lỗi trước khi thay đổi cấu hình ứng dụng.

Lưu ý: Việc cố gắng tạo và đổi API key liên tục không phải là giải pháp giải quyết tận gốc lỗi 403.

Nếu cần liên hệ hỗ trợ, hãy chuẩn bị mã lỗi và thông tin yêu cầu của bạn (nhớ che mờ các dữ liệu nhạy cảm).

Các thẻ hỏi đáp nhanh giúp ghi nhớ nguyên nhân và cách khắc phục lỗi 401 (Xác thực) và lỗi 403 (Quyền truy cập).

Xử lý lỗi Không tìm thấy (404) và Quá giới hạn (429)

Lỗi 404 hoặc thông báo không tìm thấy mô hình

Khi gặp lỗi này, bạn cần phân biệt rõ hai trường hợp nguyên nhân khác nhau:

Sai đường dẫn API (Base URL): Hãy kiểm tra xem ứng dụng kết nối của bạn có tự động thêm đuôi /chat/completions hoặc /v1 vào sau Base URL hay không. Việc điền sai Base URL ban đầu có thể tạo ra một đường dẫn gửi đi bị lặp và dẫn đến lỗi 404.

Sai mã mô hình: Đảm bảo bạn sao chép chính xác mã mô hình từ thông tin hiện hành trên tài khoản của mình. Cần lưu ý rằng tên thương mại thông thường của một mô hình có thể khác biệt hoàn toàn so với mã định danh kỹ thuật cần gửi trong trường dữ liệu model.

Lời khuyên: Mã trạng thái và cách diễn đạt lỗi có thể khác nhau tùy thuộc vào từng dịch vụ. Đừng vội kết luận nguyên nhân chỉ dựa trên một con số lỗi đơn lẻ; hãy đọc toàn bộ nội dung văn bản phản hồi chi tiết từ hệ thống.

Lỗi 429: Không gửi lại liên tục

Lỗi 429 biểu thị bạn đã vượt quá giới hạn tốc độ, hạn mức sử dụng hoặc dịch vụ phía trên đang trong tình trạng quá tải. Cách xử lý chuyên nghiệp bao gồm:

Đọc thông báo lỗi: Xác định chính xác loại giới hạn nào đang bị áp dụng.

Giảm tải: Giảm số lượng yêu cầu gửi đi đồng thời.

Giãn cách thời gian: Chờ đợi một khoảng thời gian hợp lý theo hướng dẫn cụ thể trong nội dung phản hồi (nếu có).

Kiểm tra tài khoản: Xác minh lại hạn mức tài chính hoặc số dư còn lại của tài khoản.

Giới hạn số lần thử lại: Nếu sử dụng cơ chế thử lại tự động (retry), hãy thiết lập thời gian chờ tăng dần (exponential backoff) kết hợp thêm độ trễ ngẫu nhiên. Tuyệt đối không sử dụng vòng lặp gửi lại không giới hạn.

Sơ đồ nhánh phân tích các nguyên nhân rễ củ và hành động khắc phục cụ thể đối với lỗi đường dẫn/mô hình (404) và vượt giới hạn (429).

Sự cố Timeout, Phản hồi ngắt quãng và Quy trình hỗ trợ

Timeout hoặc phản hồi streaming bị ngắt quãng

Việc xảy ra lỗi Timeout (hết thời gian chờ) chưa đủ cơ sở để kết luận mô hình hoặc dịch vụ của hệ thống đã ngừng hoạt động hoàn toàn.

Có rất nhiều yếu tố ngoại cảnh tác động trực tiếp như: độ dài của dữ liệu đầu vào (prompt), thời gian cần thiết để hệ thống xử lý tạo câu trả lời, sự ổn định của đường truyền mạng Internet, hoặc cấu hình giới hạn thời gian chờ được thiết lập bên trong ứng dụng của bạn.

Khắc phục: Hãy thử gửi các yêu cầu ngắn hơn, kiểm tra lại thiết lập thời gian chờ của ứng dụng và ghi nhận thời điểm chính xác xảy ra lỗi.

Lưu ý về chi phí: Nếu bạn thực hiện gửi lại một yêu cầu vốn đã được hệ thống xử lý thành công một phần trước đó, hãy lưu ý khả năng tài khoản của bạn vẫn có thể phát sinh thêm mức phí sử dụng cho phần tài nguyên đó.

Cần cung cấp thông tin gì khi nhờ hỗ trợ kỹ thuật?

Để đội ngũ Hajiyun có thể hỗ trợ kiểm tra và xử lý lỗi một cách nhanh chóng, một báo cáo lỗi tiêu chuẩn từ phía bạn nên cung cấp đầy đủ các thông tin kỹ thuật sau:

Thời điểm chính xác xảy ra lỗi và múi giờ hệ thống của bạn.

Tên ứng dụng kết nối đang sử dụng và số hiệu phiên bản.

Endpoint (đường dẫn API) cụ thể được gọi.

Mã mô hình được chọn để gửi yêu cầu.

Mã trạng thái HTTP nhận về kèm theo toàn bộ nội dung thông báo lỗi chi tiết.

Request ID (Mã định danh yêu cầu), nếu có hiển thị trong phản hồi.

Các bước thao tác tối thiểu để tái hiện lại lỗi đó.

Lưu ý bảo mật tối cao: Hãy luôn chủ động che mờ API key, thông tin tài khoản cá nhân và các nội dung riêng tư nhạy cảm trước khi chụp ảnh màn hình hoặc gửi thông tin chia sẻ ra ngoài.

Cấu trúc một tài liệu báo cáo sự cố chuẩn hóa giúp nhà phát triển thu thập đúng dữ liệu lỗi cần thiết và bảo vệ an toàn thông tin cá nhân.

Summary

Tổng quan về dịch vụ: Hajiyun cung cấp cổng kết nối tương thích định dạng OpenAI Chat Completions tại địa chỉ Hajiyun và hỗ trợ tiếng Việt tại Hajiyun Tiếng Việt. Base URL chuẩn để cấu hình là https://hajiyun.top/v1.

Khởi đầu an toàn: Luôn bắt đầu thử kết nối lần đầu bằng một câu hỏi ngắn, đơn giản, không chứa dữ liệu nhạy cảm và kiểm tra mức tiêu hao trước khi chạy các tác vụ quy mô lớn.

Cẩn trọng với Base URL: Tránh lỗi lặp đường dẫn (gây ra lỗi 404) bằng cách kiểm tra xem ứng dụng có tự động thêm phần /v1 hay /chat/completions vào cấu hình hay không.

Xử lý lỗi thông minh: Đọc kỹ nội dung văn bản phản hồi lỗi chứ không chỉ nhìn vào mã số lỗi. Đối với lỗi 429, hãy áp dụng cơ chế giãn cách thời gian chờ và giảm tần suất gửi yêu cầu, tuyệt đối không dùng vòng lặp gửi lại vô hạn.

Yêu cầu hỗ trợ chuẩn: Khi cần sự giúp đỡ từ đội ngũ kỹ thuật, hãy chuẩn bị báo cáo chi tiết chứa thông tin lỗi, thời gian, mô hình và luôn nhớ che mờ thông tin API key cùng dữ liệu riêng tư.

Generated by AI based on user-provided sources and instructionsTerms of Service|Privacy Policy|Learn more

Hướng dẫn kết nối Hajiyun API và xử lý các lỗi thường gặp