Cách làm việc với API Cohere

Cohere cung cấp cho các nhà phát triển quyền truy cập vào các Mô hình Ngôn ngữ Lớn (LLMs) phức tạp có khả năng hiểu và tạo ra văn bản giống như con người. Để tương tác với các mô hình này một cách lập trình, bạn cần một khóa API. Khóa này đóng vai trò là mã định danh và mật khẩu duy nhất của bạn, cho phép hệ thống của Cohere xác thực các yêu cầu của bạn và theo dõi mức sử dụng của bạn.

Hướng dẫn này sẽ đưa bạn qua các bước cần thiết: lấy khóa API của bạn, hiểu những khác biệt quan trọng giữa các loại khóa (đặc biệt liên quan đến chi phí và giới hạn sử dụng), và thực hiện một bài kiểm tra ban đầu đơn giản bằng công cụ Apidog để đảm bảo rằng khóa của bạn hoạt động đúng cách.

Bước 1: Lấy Khóa API của Cohere

Lấy khóa của bạn là bước đầu tiên và quan trọng nhất. Cohere thực hiện quy trình này khá đơn giản thông qua bảng điều khiển trực tuyến của họ.

Đi đến Bảng điều khiển Cohere: Mở trình duyệt web của bạn và đi đến điểm truy cập chính của nền tảng Cohere. Bạn thường sẽ tìm thấy trang đăng nhập hoặc đăng ký.
Truy cập Tài khoản của bạn:

Nếu bạn đã có tài khoản Cohere, hãy đăng nhập bằng thông tin xác thực của bạn.
Nếu bạn mới với Cohere, bạn sẽ cần phải đăng ký một tài khoản. Thực hiện theo quy trình đăng ký, thường liên quan đến việc cung cấp địa chỉ email và đặt mật khẩu.

Xác định Vị trí của Phần Khóa API: Một khi bạn đã đăng nhập thành công vào bảng điều khiển Cohere, hãy tìm một phần được dành riêng để quản lý Khóa API. Phần này có thể nằm dưới cài đặt tài khoản, một phần dành cho nhà phát triển, hoặc có thể truy cập trực tiếp qua một mục menu có nhãn "Khóa API". Giao diện được thiết kế dễ sử dụng, vì vậy nó sẽ khá nổi bật.

Bắt đầu Tạo Khóa: Trong phần Khóa API, bạn sẽ tìm thấy tùy chọn để tạo một khóa mới. Bạn sẽ thấy các tùy chọn phân loại giữa các loại khóa, đặc biệt là "Khóa Thử Nghiệm" và có thể là "Khóa Sản Xuất". Để thực hiện thử nghiệm và học hỏi ban đầu, hãy chọn tùy chọn để tạo một Khóa Thử Nghiệm.

Gán Tên: Một hộp thoại sẽ yêu cầu bạn đặt tên cho khóa của bạn. Chọn một tên mô tả sẽ giúp bạn nhớ mục đích của nó sau này, đặc biệt nếu bạn tạo nhiều khóa cho các dự án khác nhau. Các ví dụ bao gồm "KhóaThửNghiệmĐầuTiênCủaTôi", "KhóaDựÁnHọcTập", hoặc "KhóaKiểmTraApidog".

Tạo và Bảo mật Khóa của Bạn: Nhấn nút để xác nhận và tạo khóa (ví dụ, "Tạo Khóa Thử Nghiệm"). Cohere sẽ hiển thị khóa API mới được tạo của bạn. Đây là lần duy nhất khóa đầy đủ sẽ được hiển thị. Việc sao chép khóa này ngay lập tức và lưu trữ nó ở một vị trí cực kỳ an toàn, chẳng hạn như trình quản lý mật khẩu hoặc ghi chú an toàn là rất quan trọng. Đối xử với nó như mật khẩu. Không chia sẻ công khai, nhúng trực tiếp vào mã phía máy khách, hoặc cam kết nó vào các hệ thống quản lý phiên bản như Git. Khi bạn đóng cửa sổ bật lên hoặc điều hướng ra ngoài, bạn sẽ không thể lấy lại khóa đầy đủ nữa vì lý do bảo mật (mặc dù bạn có thể thấy tên khóa và có thể là một vài ký tự đầu/cuối trong bảng điều khiển). Nếu bạn làm mất nó, bạn sẽ cần phải tạo một cái mới.

Với khóa API của bạn đã được sao chép và bảo mật, bạn đã sẵn sàng để hiểu những gì bạn có thể làm với nó và các quy tắc liên quan.

Bước 2: Hiểu Các Loại Khóa, Chi Phí, và Giới Hạn Sử Dụng

Không phải tất cả các khóa API của Cohere đều giống nhau. Loại khóa bạn có quyết định bạn có thể sử dụng API bao nhiêu, tốc độ như thế nào, và liệu nó có phát sinh chi phí hay không. Hiểu những khác biệt này là rất quan trọng để tránh những gián đoạn hoặc phí phát sinh không mong muốn.

A. Khóa API Thử Nghiệm: Miễn Phí Để Đánh Giá

Khi bạn lần đầu đăng ký hoặc tạo một khóa mà không thiết lập thanh toán, bạn thường nhận được một Khóa Thử Nghiệm. Những khóa này được thiết kế để khám phá, học hỏi và kiểm tra quy mô nhỏ.

Chi Phí: Khóa thử nghiệm là miễn phí để sử dụng. Bạn sẽ không bị tính phí cho việc sử dụng liên quan đến một khóa thử nghiệm.
Giới Hạn Sử Dụng Tổng Thể: Giới hạn lớn nhất là giới hạn hàng tháng là 1.000 cuộc gọi API tổng cộng trên tất cả các điểm cuối của Cohere kết hợp. Điều này có nghĩa là mỗi yêu cầu bạn thực hiện (dù là đến Chat, Embed, Rerank, v.v.) đều tính vào tổng số hàng tháng này. Khi bạn đạt 1.000 cuộc gọi trong một tháng dương lịch, khóa của bạn sẽ ngừng hoạt động cho đến khi tháng sau bắt đầu.
Giới Hạn Tốc Độ (Yêu Cầu Mỗi Phút - RPM): Để đảm bảo sử dụng công bằng và ổn định cho hệ thống, các khóa thử nghiệm cũng có giới hạn tốc độ nghiêm ngặt, giới hạn số lượng yêu cầu bạn có thể gửi trong một khoảng thời gian một phút đến các điểm cuối cụ thể. Đây là điều quan trọng để nhận biết, vì việc vượt quá chúng sẽ dẫn đến lỗi 429 Too Many Requests. Các giới hạn tốc độ của Khóa Thử Nghiệm bao gồm:
Điểm cuối Chat (/v2/chat): 20 yêu cầu mỗi phút. Đây là điểm cuối được sử dụng cho AI hội thoại, tạo văn bản, tóm tắt, v.v.
Điểm cuối Embed (/v2/embed) - Văn bản: 100 yêu cầu mỗi phút. Được sử dụng để tạo các vector nhúng cho dữ liệu văn bản (tìm kiếm ngữ nghĩa, phân nhóm).
Điểm cuối Embed (/v2/embed) - Hình ảnh: 5 yêu cầu mỗi phút. Được sử dụng để tạo các vector nhúng cho dữ liệu hình ảnh (tìm kiếm đa phương thức).
Điểm cuối Rerank (/v2/rerank): 10 yêu cầu mỗi phút. Được sử dụng để cải thiện xếp hạng tính liên quan của kết quả tìm kiếm.
Điểm cuối Tokenize (/v2/tokenize): 100 yêu cầu mỗi phút. Được sử dụng để xem cách văn bản được chia thành các token bởi các mô hình của Cohere.
Điểm cuối Classify (/v1/classify): 100 yêu cầu mỗi phút. Được sử dụng cho các nhiệm vụ phân loại văn bản (cũ, hiện tại ưu tiên tinh chỉnh).
Các Điểm cuối Legacy (Tóm tắt, Tạo): 5 yêu cầu mỗi phút.
Các Điểm cuối Khác/Mặc định: Các giới hạn có thể áp dụng cho các điểm cuối ít phổ biến hơn hoặc quản lý khác.

Các khóa thử nghiệm rất lý tưởng cho:

Học cách hoạt động của API Cohere.
Thử nghiệm với các mô hình và tham số khác nhau trong Playground hoặc thông qua các cuộc gọi trực tiếp.
Xây dựng các dự án cá nhân nhỏ hoặc nguyên mẫu với mức sử dụng hạn chế.
Đánh giá khả năng của Cohere trước khi cam kết sử dụng trả phí.

Nếu bạn thường xuyên đạt giới hạn hàng tháng hoặc các giới hạn tốc độ mỗi phút, đó là tín hiệu mạnh mẽ rằng bạn cần nâng cấp lên khóa Sản Xuất.

B. Khóa API Sản Xuất: Để Xây Dựng và Mở Rộng

Khi bạn đã sẵn sàng để xây dựng các ứng dụng với người dùng thực, xử lý khối lượng công việc lớn hơn, hoặc vượt qua các giới hạn thử nghiệm, bạn sẽ cần một Khóa Sản Xuất. Điều này yêu cầu bạn thiết lập thông tin thanh toán trong tài khoản Cohere của bạn.

Chi Phí: Các khóa sản xuất hoạt động theo mô hình trả tiền khi sử dụng, chủ yếu dựa vào sử dụng token. Token là các đơn vị văn bản (khoảng tương ứng với từ hoặc phần của từ) mà các mô hình xử lý. Bạn sẽ bị tính phí cho cả các token bạn gửi cho mô hình (token đầu vào) và các token mà mô hình tạo ra trong phản hồi của nó (token đầu ra).
Giá Có Thể Khác Nhau Theo Mô Hình: Các mô hình mạnh mẽ hơn thường tốn nhiều phí hơn mỗi token so với các mô hình nhẹ hơn, nhanh hơn.
Ví Dụ Giá (Minh Họa - kiểm tra trang giá chính thức của Cohere để biết tỷ lệ hiện tại):
Mô hình Command R: Có thể tốn khoảng $0.50 cho mỗi triệu token đầu vào và $1.50 cho mỗi triệu token đầu ra. (Lưu ý: Kết quả tìm kiếm trước đó cho biết $2.50 đầu vào / $10.00 đầu ra cho Command R - sử dụng các giá trị đó: $2.50 / 1 triệu token đầu vào, $10.00 / 1 triệu token đầu ra.)
Mô hình Command R+: Khả năng tốt hơn, nó có thể sẽ có giá cao hơn, có thể là $3.00 cho mỗi triệu token đầu vào và $15.00 cho mỗi triệu token đầu ra.
Các Mô Hình Nhúng (ví dụ, embed-english-v3.0): Các mô hình nhúng thường chỉ được định giá trên token đầu vào, vì chúng không tạo ra các đầu ra văn bản dài. Giá có thể khoảng $0.10 cho mỗi triệu token đầu vào.
Tính Toán Token: Cohere cung cấp một điểm cuối Tokenizer và tài liệu để giúp bạn hiểu cách văn bản chuyển đổi thành token để ước tính chi phí chính xác. Các đầu vào và đầu ra dài hơn tự nhiên có chi phí cao hơn.
Giới Hạn Sử Dụng Tổng Thể: Không có giới hạn tổng số cuộc gọi hàng tháng cho các khóa sản xuất. Bạn có thể thực hiện bất kỳ số lượng cuộc gọi nào cần thiết, miễn là bạn giữ trong giới hạn tốc độ và quản lý chi phí của bạn.
Giới Hạn Tốc Độ (Yêu Cầu Mỗi Phút - RPM): Các khóa sản xuất được hưởng lợi từ các giới hạn tốc độ cao hơn nhiều, cho phép các ứng dụng xử lý khối lượng lưu lượng lớn hơn nhiều:
Điểm cuối Chat (/v2/chat): 500 yêu cầu mỗi phút (so với 20/yêu cầu cho Thử Nghiệm).
Điểm cuối Embed (/v2/embed) - Văn bản: 2.000 yêu cầu mỗi phút (so với 100/yêu cầu).
Điểm cuối Embed (/v2/embed) - Hình ảnh: 400 yêu cầu mỗi phút (so với 5/yêu cầu).
Điểm cuối Rerank (/v2/rerank): 1.000 yêu cầu mỗi phút (so với 10/yêu cầu).
Điểm cuối Tokenize (/v2/tokenize): 2.000 yêu cầu mỗi phút.
Điểm cuối Classify (/v1/classify): 1.000 yêu cầu mỗi phút.
Tăng Giới Hạn Tốc Độ: Đối với các ứng dụng có lưu lượng cao, có thể yêu cầu tăng giới hạn tốc độ thêm bằng cách liên hệ với bộ phận hỗ trợ của Cohere.

Các khóa sản xuất cần thiết cho:

Phát triển và triển khai các ứng dụng dành cho người dùng cuối.
Xử lý các khối lượng yêu cầu API nhất quán hoặc lớn.
Bất kỳ trường hợp sử dụng thương mại nào.
Mở khóa tiềm năng hiệu suất đầy đủ mà không bị ràng buộc bởi các giới hạn thử nghiệm.

C. Chọn Khóa Đúng:

Bắt đầu với Thử Nghiệm: Luôn bắt đầu với một khóa thử nghiệm cho việc học hỏi và phát triển ban đầu.
Theo Dõi Sử Dụng: Theo dõi khối lượng và tần suất cuộc gọi của bạn.
Nâng Cấp Khi Cần Thiết: Nếu ứng dụng của bạn thường xuyên đạt giới hạn tốc độ, vượt quá mức 1.000 cuộc gọi hàng tháng, hoặc nếu bạn đang chuẩn bị công khai hoặc thương mại hóa, hãy nâng cấp lên khóa sản xuất bằng cách thêm chi tiết thanh toán trong bảng điều khiển Cohere.

Okay, dưới đây là phần Bước 3 đã được chỉnh sửa tập trung vào việc kiểm tra yêu cầu trò chuyện streaming được cung cấp trong lệnh curl sử dụng Apidog, trình bày bằng Markdown:

Bước 3: Thực hiện Cuộc Gọi Kiểm Tra API Cơ Bản Cho Trò Chuyện Streaming Với Apidog

Trước khi tích hợp API vào mã phức tạp, đặc biệt là cho các phản hồi streaming, thật hữu ích khi thực hiện một bài kiểm tra trực tiếp. Apidog cho phép bạn sao chép cấu trúc lệnh curl để xác minh khóa của bạn và hiểu luồng yêu cầu/phản hồi cơ bản cho streaming.

Mở Apidog: Mở ứng dụng Apidog trên máy tính của bạn.
Tạo một Yêu Cầu Mới: Nhấn nút '+' hoặc tương đương để tạo một yêu cầu API mới. Đặt tên cho nó một cái gì đó mô tả, như "Kiểm Tra Trò Chuyện Streaming Cohere".
Cấu Hình Điểm Cuối:

Phương Thức HTTP: Chọn POST.
URL: Nhập URL điểm cuối Chat v2 của Cohere: https://api.cohere.ai/v2/chat

4. Thiết Lập Tiêu Đề:

Đi đến tab "Tiêu đề". Bạn sẽ cần thêm một số tiêu đề dựa trên lệnh curl:
Accept: Khóa: Accept, Giá trị: application/json
Content-Type: Khóa: Content-Type, Giá trị: application/json
Authorization: Khóa: Authorization, Giá trị: Bearer YOUR_API_KEY (Thay YOUR_API_KEY bằng khóa API thực tế của bạn. Đảm bảo có một khoảng trắng sau Bearer).

5. Xây Dựng Thân Yêu Cầu (với Streaming Được Kích Hoạt):

Đi đến tab "Thân".
Chọn tùy chọn cho đầu vào "thô".
Chọn JSON làm định dạng.
Dán nội dung JSON sau, phản ánh dữ liệu của lệnh curl, bao gồm cờ quan trọng "stream": true:

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "Hello world!"
    }
  ]
}

(Lưu ý: Ví dụ curl sử dụng "role": "user" (viết thường) và mô hình "command-a-03-2025". Tôi đã giữ "role": "USER" và mô hình "command-r" cho sự nhất quán với các ví dụ trước đó, nhưng bạn nên điều chỉnh mô hình và kiểu chữ trong JSON trên để khớp chính xác với yêu cầu cụ thể mà bạn dự định kiểm tra nếu khác.)

6. Thực Hiện Yêu Cầu: Nhấn nút "Gửi" trong Apidog.

7. Phân Tích Phản Hồi (Chi Tiết Streaming):

Mã Trạng Thái: Bạn vẫn sẽ nhận được mã trạng thái 200 OK nếu yêu cầu ban đầu được máy chủ chấp nhận.
Tiêu Đề Phản Hồi: Kiểm tra các tiêu đề phản hồi xem có dấu hiệu của streaming, chẳng hạn như Transfer-Encoding: chunked.
Thân Phản Hồi: Cách Apidog hiển thị phản hồi streaming có thể khác nhau. Nó có thể:
Chờ cho đến khi luồng hoàn thành và hiển thị văn bản được nối hoàn toàn hoặc tải trọng sự kiện cuối cùng.
Hiển thị các đoạn thô hoặc Sự kiện Gửi từ Máy chủ (SSE) khi chúng đến, có thể giống như nhiều đối tượng JSON liên tiếp.
Nó có khả năng sẽ không hiển thị văn bản mượt mà từng token một như một ứng dụng được xây dựng riêng.
Nội Dung: Hãy xem xét nội dung thân phản hồi. Bạn nên thấy các sự kiện liên quan đến luồng, chẳng hạn như các sự kiện text-generation chứa các phần của phản hồi "Hello world!" và cuối cùng một sự kiện stream-end chỉ ra rằng quá trình đã hoàn tất.
Lỗi: Nếu bạn gặp lỗi (401, 403, 400, 429), hãy chẩn đoán chúng như đã mô tả trước đó (kiểm tra khóa API, tính hợp lệ của JSON, giới hạn tốc độ). Một lỗi 400 Bad Request có thể xảy ra nếu mô hình được chỉ định không hỗ trợ streaming hoặc nếu các tham số khác không tương thích.

Bài kiểm tra này giúp xác nhận rằng API chấp nhận yêu cầu streaming của bạn và rằng khóa của bạn hợp lệ cho loại tương tác này, ngay cả khi Apidog không phải là công cụ lý tưởng để hình dung tính chất thời gian thực của luồng. Nó xác minh rằng việc thiết lập yêu cầu cơ bản là đúng.

Kết Luận

Bây giờ bạn đã có khóa API của Cohere và hiểu những khác biệt quan trọng giữa các khóa Thử Nghiệm và Sản Xuất, đặc biệt liên quan đến giới hạn 1.000 cuộc gọi hàng tháng và giới hạn tốc độ mỗi phút trên các khóa Thử Nghiệm so với các mô hình thanh toán theo mức tiêu thụ, dựa trên token và các giới hạn cao hơn của các khóa Sản Xuất. Bạn cũng đã thực hiện một bài kiểm tra cơ bản nhưng thiết yếu bằng Apidog để xác nhận rằng khóa của bạn hoạt động và bạn có thể cấu trúc một cuộc gọi API đơn giản.

Nền tảng này rất quan trọng để tương tác hiệu quả với API Cohere. Hãy nhớ giữ khóa của bạn an toàn, theo dõi mức sử dụng của bạn theo các giới hạn (đặc biệt là đối với một khóa Thử Nghiệm), và tham khảo tài liệu của Cohere để biết thông tin chi tiết về các mô hình cụ thể, các tham số nâng cao và cách sử dụng SDK khi bạn bắt đầu xây dựng các ứng dụng tinh vi hơn.