API Chat Completions của OpenAI: Hướng dẫn tính năng và cách sử dụng

Xây dựng ứng dụng sử dụng AI không chỉ là khiến một mô hình tạo phản hồi. Bạn còn cần một cách đáng tin cậy để quản lý cuộc trò chuyện, định hướng phản hồi và kết nối mọi thứ với ứng dụng của mình. OpenAI Chat Completions API giúp thực hiện điều này bằng cách cho nhà phát triển quyền kiểm soát cách AI xử lý thông điệp và tạo câu trả lời. Nếu muốn hiểu cách API này hoạt động và cách sử dụng trong các dự án của mình, bài viết này sẽ hướng dẫn mọi điều bạn cần biết.

OpenAI Chat Completions API cho phép nhà phát triển tích hợp các mô hình ngôn ngữ của OpenAI vào ứng dụng và dịch vụ. API tạo phản hồi từ một chuỗi thông điệp, đồng thời hỗ trợ các tác vụ như hội thoại, trả lời câu hỏi, tạo nội dung và phân tích văn bản.

Chat Completions vẫn được hỗ trợ. Với các dự án mới, OpenAI khuyến nghị sử dụng Responses API. Hướng dẫn này tập trung vào Chat Completions để giải thích định dạng thông điệp, các tham số yêu cầu và cách dùng với các SDK tương thích.

Không giống endpoint Completions cũ (/v1/completions) chỉ nhận một prompt văn bản, Chat Completions nhận một danh sách thông điệp có cấu trúc. Mỗi thông điệp có một vai trò, chẳng hạn developer, user hoặc assistant, giúp mô hình diễn giải hướng dẫn và ngữ cảnh hội thoại. Các vai trò và loại nội dung được hỗ trợ phụ thuộc vào mô hình đã chọn.

Nhà phát triển có thể dùng API để xây dựng nhiều tính năng sử dụng AI, gồm:

• Ứng dụng hội thoại: Tạo chatbot AI, trợ lý ảo và hệ thống hỗ trợ khách hàng phản hồi thông điệp của người dùng.

• Tạo nội dung: Tạo bài viết, mô tả sản phẩm, email, bản tóm tắt và các nội dung văn bản khác.

• Phân tích văn bản: Phân loại văn bản, trích xuất thông tin, phân tích cảm xúc và xác định các ý chính trong tài liệu.

• Hỗ trợ lập trình: Tạo đoạn mã, giải thích các khái niệm lập trình và giúp nhà phát triển khắc phục lỗi.

• Xử lý ngôn ngữ: Dịch, viết lại, đơn giản hóa và hiệu đính văn bản ở nhiều ngôn ngữ khác nhau.

API cung cấp một cách linh hoạt để kết nối các mô hình ngôn ngữ với phần mềm hiện có, cho phép nhà phát triển tích hợp phản hồi do AI tạo vào ứng dụng mà không cần tự xây dựng và lưu trữ các mô hình ngôn ngữ.

Chat Completions API hoạt động theo quy trình yêu cầu - phản hồi. Ứng dụng gửi một yêu cầu chứa mã định danh mô hình và danh sách thông điệp đến endpoint API. Mô hình được chọn xử lý dữ liệu đầu vào và trả về phản hồi được tạo.

Quy trình cơ bản gồm các bước sau:

1. Chuẩn bị cuộc hội thoại: Ứng dụng thu thập dữ liệu người dùng nhập và sắp xếp thành một danh sách thông điệp. Các thông điệp từ cuộc hội thoại trước cũng có thể được đưa vào để cung cấp ngữ cảnh.

2. Gửi yêu cầu API: Ứng dụng gửi yêu cầu POST đến https://api.openai.com/v1/chat/completions cùng mô hình đã chọn và danh sách thông điệp. Yêu cầu sử dụng tiêu đề Authorization: Bearer <API_KEY>. Phương thức client.chat.completions.create() của Python SDK xử lý cấu trúc yêu cầu và việc xác thực này.

3. Xử lý dữ liệu đầu vào: Mô hình diễn giải các thông điệp, xem xét vai trò và nội dung của chúng, rồi tạo phản hồi dựa trên ngữ cảnh và các tham số được cung cấp.

4. Nhận phản hồi: Một yêu cầu không truyền luồng sẽ trả về phản hồi JSON chứa phần hoàn tất được tạo và siêu dữ liệu. Khi bật truyền luồng, API gửi một chuỗi sự kiện do máy chủ gửi (SSE), được ứng dụng xử lý ngay khi nhận được.

5. Hiển thị hoặc xử lý đầu ra: Ứng dụng trích xuất thông điệp được tạo rồi hiển thị cho người dùng hoặc chuyển nó đến một thành phần khác của ứng dụng.

Quy trình này dựa trên mô hình yêu cầu và phản hồi của OpenAI Chat Completions API.

Để sử dụng hiệu quả Chat Completions API, nhà phát triển cần hiểu các tham số yêu cầu chính và cách chúng ảnh hưởng đến hành vi của mô hình.

Tham số model chỉ định mô hình ngôn ngữ nào sẽ xử lý yêu cầu. Các mô hình khác nhau có thể cung cấp những khả năng, tốc độ phản hồi, hiệu năng suy luận và mức giá khác nhau.

Nhà phát triển nên chọn mô hình theo độ phức tạp của tác vụ, chất lượng phản hồi mong muốn, yêu cầu về độ trễ và ngân sách.

Tham số messages chứa một mảng các thông điệp hội thoại. Mỗi thông điệp thường gồm trường role và content.

Các vai trò phổ biến gồm:

Hãy chọn vai trò chỉ dẫn được mô hình của bạn hỗ trợ; không cần gửi đồng thời thông điệp system và developer cho cùng một chỉ dẫn. Để duy trì ngữ cảnh qua các lượt, hãy đưa lịch sử hội thoại liên quan vào từng yêu cầu. Các nhà cung cấp tương thích có thể hỗ trợ những vai trò khác nhau, vì vậy khi điều chỉnh một hoạt động tích hợp, hãy làm theo tài liệu về mô hình của họ.

Trên các mô hình và cấu hình hỗ trợ, temperature kiểm soát độ ngẫu nhiên khi lấy mẫu. Tài liệu tham chiếu API quy định phạm vi từ 0 đến 2, với giá trị mặc định là 1. Hãy kiểm tra khả năng hỗ trợ tham số của mô hình đã chọn trước khi đặt giá trị tùy chỉnh.

• Nhiệt độ thấp: Tạo ra các phản hồi tập trung và dễ dự đoán hơn, hữu ích cho việc phân loại, trích xuất thông tin và các tác vụ có cấu trúc.

• Nhiệt độ cao: Cho phép văn bản được tạo có nhiều biến thể hơn, hữu ích cho việc lên ý tưởng và viết sáng tạo.

Một số cấu hình suy luận không chấp nhận giá trị tùy chỉnh cho temperature hoặc top_p. Với các cấu hình đó, hãy bỏ qua những tham số lấy mẫu này và thay vào đó sử dụng các tùy chọn được hỗ trợ, chẳng hạn như mức độ nỗ lực suy luận và giới hạn đầu ra.

Khi được hỗ trợ, top_p kiểm soát việc chọn token thông qua phương pháp lấy mẫu hạt nhân. Tham số này đặt ngưỡng xác suất tích lũy dùng để chọn các token ứng viên.

Ví dụ, giá trị 0.1 nghĩa là mô hình xem xét các token nằm trong 10% khối xác suất tích lũy cao nhất. Giá trị thấp hơn thường tạo đầu ra tập trung hơn, trong khi giá trị cao hơn cho phép nhiều biến thể hơn.

OpenAI khuyến nghị điều chỉnh temperature hoặc top_p thay vì thay đổi đồng thời cả hai.

Tham số max_completion_tokens đặt số token tối đa mà mô hình có thể tạo trong một phản hồi, bao gồm cả token suy luận khi áp dụng.

Đặt giới hạn phù hợp giúp nhà phát triển kiểm soát độ dài đầu ra và quản lý mức tiêu thụ token. Nếu mô hình chạm giới hạn này trước khi hoàn tất phản hồi, phần hoàn tất có thể kết thúc với lý do hoàn tất length.

Tham số stream xác định liệu API trả về phản hồi được tạo một lần hay dần dần trong quá trình tạo.

• false: Trả về phản hồi hoàn chỉnh sau khi quá trình tạo kết thúc.

• true: Truyền dữ liệu phản hồi đến ứng dụng qua sự kiện do máy chủ gửi (SSE).

Truyền luồng hữu ích cho giao diện trò chuyện và các ứng dụng mà người dùng được lợi khi thấy phản hồi xuất hiện dần, thay vì phải chờ toàn bộ đầu ra.

Tham số response_format chọn định dạng đầu ra trên các mô hình được hỗ trợ. Văn bản là mặc định. Đặt type thành json_object sẽ bật chế độ JSON, tạo ra JSON hợp lệ nhưng không áp dụng một lược đồ cụ thể. Hãy thêm chỉ dẫn trả về JSON vào messages.

Để có các trường và kiểu dữ liệu có thể dự đoán, hãy dùng Structured Outputs dựa trên JSON Schema với type: "json_schema" và strict: true trên một mô hình tương thích. Ở chế độ nghiêm ngặt, chỉ có thể dùng tập con được hỗ trợ của JSON Schema. Trước khi xử lý kết quả, hãy kiểm tra xem có từ chối hoặc phản hồi bị cắt ngắn hay không. Xem hướng dẫn Structured Outputs để biết chi tiết cấu hình.

Tham số tool_choice kiểm soát việc chọn công cụ khi mô hình hỗ trợ gọi công cụ qua Chat Completions. Khả năng hỗ trợ phụ thuộc vào cả mô hình lẫn cấu hình suy luận; một số mô hình mới hơn yêu cầu Responses API để sử dụng công cụ. Hãy kiểm tra các yêu cầu này trước khi thêm công cụ vào yêu cầu.

Các thiết lập phổ biến gồm:

• none: Ngăn mô hình gọi công cụ.

• auto: Cho phép mô hình quyết định có gọi một công cụ sẵn có hay không.

• required: Yêu cầu mô hình gọi một hoặc nhiều công cụ.

Khả năng này hỗ trợ gọi hàm, cho phép ứng dụng kết nối các quyết định do mô hình tạo ra với các hàm, cơ sở dữ liệu và dịch vụ bên ngoài. Ứng dụng chịu trách nhiệm thực thi hàm được yêu cầu và trả kết quả của hàm đó về cho mô hình.

Dùng tài liệu tham chiếu Chat Completions API để xem định nghĩa tham số và các yêu cầu về khả năng tương thích của mô hình. Ví dụ Python bên dưới sử dụng một yêu cầu văn bản cơ bản, không có công cụ.

Nhà phát triển có thể truy cập Chat Completions API qua các yêu cầu HTTP hoặc SDK chính thức. Ví dụ sau dùng Python để gửi một yêu cầu hội thoại và lấy phản hồi được tạo.

Bước 1. Lấy khóa API

Tạo khóa API trên nền tảng OpenAI API và đảm bảo tài khoản của bạn có quyền truy cập vào mô hình đã chọn, đồng thời có đủ tín dụng API hoặc khả năng thanh toán. Hãy lưu khóa trong biến môi trường thay vì mã nguồn ứng dụng. Trên macOS hoặc Linux, hãy chạy:

Thay YOUR_API_KEY bằng khóa của bạn. Trên Windows, hãy đặt cùng biến OPENAI_API_KEY trong shell hoặc môi trường hệ thống.

Bước 2. Cài đặt OpenAI Python SDK

Cài đặt thư viện Python chính thức bằng pip:

Bước 3. Khởi tạo ứng dụng khách API

Nhập SDK và khởi tạo ứng dụng khách. OpenAI() tự động đọc biến môi trường OPENAI_API_KEY đã được đặt ở Bước 1.

Bước 4. Gửi yêu cầu chat completion

Gọi client.chat.completions.create() với một mô hình và danh sách messages. Ví dụ này dùng gpt-6-astra với mức nỗ lực suy luận thấp và giới hạn tổng số token được tạo là 4.096. Nếu tài khoản của bạn không dùng được mô hình này, hãy chọn một mô hình hỗ trợ Chat Completions và điều chỉnh tham số cho phù hợp với tài liệu của mô hình đó.

Trong ví dụ này:

• model xác định mô hình ngôn ngữ dùng để tạo phản hồi.

• messages cung cấp chỉ dẫn và dữ liệu đầu vào của người dùng.

• reasoning_effort đặt mức nỗ lực suy luận cho các mô hình hỗ trợ tham số này.

• max_completion_tokens giới hạn số token được tạo, bao gồm cả token suy luận. Tham số này không đảm bảo một lượng văn bản hiển thị cụ thể.

• response.choices[0].message.content trích xuất phản hồi của trợ lý.

Xử lý phản hồi API

Với yêu cầu không truyền luồng này, API trả về JSON chứa kết quả hoàn thành và siêu dữ liệu yêu cầu. Python SDK phân tích dữ liệu đó thành một đối tượng ChatCompletion, vì vậy ví dụ truy cập các trường thông qua thuộc tính như response.choices[0].message.content.

Các trường phản hồi quan trọng gồm có:

Trường finish_reason có thể giúp nhà phát triển hiểu quá trình tạo nội dung đã kết thúc như thế nào. Các giá trị thường gặp gồm stop, length và tool_calls.

Nhà phát triển cũng có thể kiểm tra trường usage để theo dõi lượng token đầu vào và đầu ra đã dùng, hữu ích cho việc ước tính chi phí API và tối ưu hóa mức sử dụng ứng dụng.

Ví dụ này minh họa phản hồi văn bản cơ bản. Khi thêm truyền luồng, đầu ra có cấu trúc hoặc công cụ, hãy cập nhật cả logic xử lý yêu cầu lẫn phản hồi cho phù hợp với mô hình và endpoint đã chọn.

Với các nhà phát triển đang tìm kiếm giải pháp thay thế cho OpenAI Chat Completions API, Kimi API cung cấp quyền truy cập vào các mô hình ngôn ngữ lớn của Moonshot AI thông qua định dạng API tương thích với OpenAI.

Kimi cung cấp các giao diện Chat Completions, Responses và Messages. Ví dụ dưới đây sử dụng endpoint Chat Completions tương thích với OpenAI của Kimi để bạn có thể tái sử dụng quy trình làm việc với SDK đã giới thiệu ở trên. Hãy cấu hình khóa Kimi API, đặt URL cơ sở của Kimi và chọn một mô hình được hỗ trợ. Tham khảo tài liệu riêng của Kimi về tham số mô hình, vai trò tin nhắn và hỗ trợ công cụ.

Bước 1. Lấy khóa Kimi API

Đăng ký trên nền tảng Kimi API và tạo khóa API trong bảng điều khiển dành cho nhà phát triển. Hãy kiểm tra số dư, quyền truy cập mô hình và giới hạn tốc độ của tài khoản trước khi gửi yêu cầu đầu tiên.

Lưu khóa Kimi trong một biến môi trường riêng. Trên macOS hoặc Linux, hãy chạy:

Thay YOUR_KIMI_API_KEY bằng khóa Kimi của bạn. Trên Windows, hãy đặt cùng biến KIMI_API_KEY trong môi trường của bạn.

Bước 2. Cài đặt OpenAI Python SDK

Nếu SDK chưa được cài đặt, hãy chạy:

Bước 3. Cấu hình ứng dụng khách Kimi API

Tạo một kimi_client riêng bằng URL cơ sở của Kimi và biến KIMI_API_KEY đã đặt ở Bước 1. Việc đọc khóa bằng os.environ sẽ khiến lỗi thiếu biến môi trường hiện ra ngay lập tức.

Bước 4. Gửi yêu cầu Chat Completions

Dùng cùng phương thức SDK với ứng dụng khách Kimi. Yêu cầu này chọn kimi-k3, sử dụng vai trò system mà Kimi hỗ trợ cho các chỉ dẫn và trả về phản hồi văn bản không truyền luồng.

• Tùy chọn mô hình cho các khối lượng công việc khác nhau: Kimi K3.1 Pro hỗ trợ suy luận phức tạp, lập trình dài hạn và công việc tri thức. Biến thể Highspeed của nó cho đầu ra nhanh hơn với cùng năng lực mô hình. Ví dụ trên dùng Kimi K3; hãy xem danh sách mô hình hiện tại để biết tình trạng khả dụng và hướng dẫn chuyển đổi.

• Tương thích OpenAI API: Nhà phát triển đã quen với định dạng OpenAI Chat Completions có thể tái sử dụng cấu trúc yêu cầu tương tự và các quy trình SDK được hỗ trợ khi tích hợp mô hình Kimi.

• Hội thoại nhiều lượt: Nhà phát triển có thể cung cấp lịch sử tin nhắn để hỗ trợ các cuộc hội thoại có nhận biết ngữ cảnh, trợ lý ảo và ứng dụng tương tác.

• Truyền luồng và gọi hàm: API hỗ trợ phản hồi truyền luồng và quy trình gọi công cụ, cho phép nhà phát triển xây dựng ứng dụng tương tác hơn và kết nối mô hình với các hàm bên ngoài.

• Đầu vào đa phương thức: Các mô hình Kimi được hỗ trợ có thể xử lý nhiều loại đầu vào, gồm văn bản, hình ảnh và video, tùy thuộc vào khả năng của mô hình.

Khi làm việc với Chat Completions API, nhà phát triển có thể gặp lỗi liên quan đến xác thực, cấu hình API, tính khả dụng của mô hình hoặc giới hạn yêu cầu. Hiểu các vấn đề thường gặp này có thể giúp bạn xác định lỗi và vận hành tích hợp trơn tru:

• Khóa API không hợp lệ hoặc bị thiếu: Lỗi xác thực, chẳng hạn HTTP 401, có thể xảy ra khi khóa API không chính xác, đã hết hạn, bị thu hồi hoặc chưa được cấu hình đúng. Hãy kiểm tra khóa có hợp lệ không, biến môi trường đã được tải đúng chưa và yêu cầu có bao gồm thông tin xác thực phù hợp không.

• URL cơ sở API không chính xác: Các yêu cầu gửi đến endpoint không đúng có thể trả về lỗi như 404 hoặc lỗi kết nối. Hãy xác minh URL cơ sở khớp với tài liệu của nhà cung cấp API và yêu cầu sử dụng đúng đường dẫn endpoint. Khi chuyển đổi giữa OpenAI và các nhà cung cấp tương thích, hãy nhớ cập nhật URL cơ sở tương ứng.

• ID mô hình không hợp lệ hoặc không khả dụng: Một yêu cầu có thể thất bại nếu tên mô hình được chỉ định không chính xác, không khả dụng với tài khoản của bạn hoặc không được endpoint đã chọn hỗ trợ. Hãy kiểm tra tài liệu mô hình của nhà cung cấp và xác nhận ID mô hình khớp với ID khả dụng cho tài khoản API của bạn.

• Vượt quá độ dài ngữ cảnh: Nếu tổng số thông điệp đầu vào và đầu ra được tạo vượt quá cửa sổ ngữ cảnh của mô hình, API có thể từ chối yêu cầu. Hãy giảm độ dài đầu vào, xóa lịch sử hội thoại không cần thiết hoặc tóm tắt các thông điệp trước đó trước khi gửi lại yêu cầu.

• Đầu ra bị cắt ngắn: Phản hồi có thể dừng trước khi hoàn thành nội dung được yêu cầu nếu chạm giới hạn max_completion_tokens. Hãy tăng giới hạn token nếu được hỗ trợ hoặc chia tác vụ tạo nội dung dài thành các yêu cầu nhỏ hơn. Bạn cũng có thể kiểm tra choices[].finish_reason để biết liệu phản hồi có kết thúc do giới hạn length hay không.

• Vượt quá giới hạn tốc độ hoặc hạn ngạch: Với OpenAI, HTTP 429 có thể cho biết đã chạm giới hạn tốc độ yêu cầu hoặc token, giới hạn chi tiêu hoặc một hạn chế sử dụng khác. Hãy kiểm tra loại lỗi và mã lỗi trước khi thử lại. Với giới hạn tốc độ tạm thời, hãy giảm tần suất yêu cầu và tuân theo Retry-After khi có, hoặc sử dụng cơ chế lùi theo cấp số nhân.

Nếu lỗi cho biết đã hết tín dụng hoặc chạm giới hạn thanh toán hay chi tiêu, hãy kiểm tra số dư và chế độ cài đặt thanh toán của tài khoản; việc thử lại nhiều lần sẽ không khôi phục quyền truy cập. Khi sử dụng Kimi hoặc một nhà cung cấp tương thích khác, hãy tham khảo tài liệu về mã lỗi của nhà cung cấp đó, vì mã trạng thái và quy tắc hạn ngạch có thể khác nhau.

Để gỡ lỗi hiệu quả hơn, hãy kiểm tra mã trạng thái HTTP và thông báo lỗi do API trả về trước khi thay đổi các tham số yêu cầu. Những thông tin này có thể giúp phân biệt vấn đề xác thực, lỗi cấu hình và giới hạn sử dụng.

Chat Completions API có thể hỗ trợ nhiều tình huống ứng dụng khác nhau. Định dạng thông điệp có cấu trúc và các tham số tạo nội dung có thể tùy chỉnh khiến API này phù hợp cho cả các tính năng đơn giản dựa trên văn bản lẫn quy trình AI phức tạp hơn.

• Chatbot AI và trợ lý ảo: Nhà phát triển có thể dùng API để xây dựng trợ lý hội thoại cho website, ứng dụng di động và nền tảng chăm sóc khách hàng. Bằng cách truyền các thông điệp trước đó vào những yêu cầu tiếp theo, ứng dụng có thể duy trì ngữ cảnh hội thoại và đưa ra phản hồi phù hợp hơn.

• Sáng tạo nội dung và chỉnh sửa văn bản: API có thể tạo và chuyển đổi văn bản dựa trên chỉ dẫn của người dùng. Ứng dụng có thể dùng API để phác thảo bài đăng blog, viết nội dung tiếp thị, tóm tắt nội dung dài, viết lại đoạn văn và điều chỉnh văn phong cho các đối tượng cũng như mục đích khác nhau.

• Phân loại văn bản và trích xuất thông tin: Doanh nghiệp có thể tích hợp API vào các quy trình xử lý khối lượng lớn văn bản. Chẳng hạn, API có thể phân loại phản hồi của khách hàng, xác định cảm xúc, trích xuất thông tin quan trọng từ thông điệp và sắp xếp nội dung phi cấu trúc vào các danh mục được xác định trước.

• Trợ lý lập trình: API có thể hỗ trợ các công cụ phát triển phần mềm bằng cách tạo mã, giải thích khái niệm lập trình, đề xuất giải pháp và giúp nhà phát triển xác định lỗi. Ứng dụng cũng có thể kết nối mô hình với các công cụ phát triển bên ngoài thông qua function calling.

• Quy trình nghiệp vụ ứng dụng AI: Nhà phát triển có thể tích hợp API vào các ứng dụng doanh nghiệp để tự động hóa những tác vụ lặp lại liên quan đến ngôn ngữ. Ví dụ gồm xử lý yêu cầu của khách hàng, tạo báo cáo, trích xuất thông tin từ tài liệu và chuẩn bị phản hồi dựa trên chỉ dẫn được xác định trước.

OpenAI Chat Completions API mang đến cho nhà phát triển một cách thiết thực để đưa AI hội thoại vào ứng dụng và tạo ra trải nghiệm hữu ích hơn cho người dùng. Việc chọn đúng mô hình, hiểu các tham số của mô hình và xử lý cẩn thận phản hồi từ API có thể tạo ra khác biệt đáng kể về hiệu quả hoạt động của ứng dụng. Tuy nhiên, nhà phát triển không nhất thiết phải phụ thuộc vào một nhà cung cấp duy nhất khi xây dựng các giải pháp ứng dụng AI. Nếu muốn tìm hiểu một lựa chọn khác, hãy dùng thử Kimi API và xem cách thiết lập tương thích với OpenAI của nó phù hợp với nhu cầu phát triển của bạn như thế nào.