Việc lấy API key của OpenAI rất dễ. Còn việc thiết kế quyền truy cập OpenAI API sao cho luôn an toàn, có thể kiểm thử và thay thế được khi sản phẩm của bạn bổ sung thêm nhiều model mới mới là công việc kỹ thuật thực sự.
Với một bản prototype, một key cá nhân và một lần gọi model có thể là đủ. Một sản phẩm đa mô hình ở môi trường production cần một thiết lập khác: thông tin xác thực theo phạm vi project, các môi trường tách biệt, kiểm tra endpoint và capability rõ ràng, xử lý giới hạn tốc độ, khả năng quan sát mức sử dụng, và một lộ trình được kiểm soát để đưa vào các nhà cung cấp dự phòng.
Hướng dẫn này chuyển những yêu cầu đó thành một checklist triển khai. Trước hết, nó bao quát quyền truy cập trực tiếp vào OpenAI, sau đó chỉ ra cách một gateway tương thích OpenAI có thể giảm bớt khối lượng vận hành khi sản phẩm của bạn mở rộng vượt ra ngoài một nhà cung cấp.
Đã kiểm tra ngày 28 tháng 7, 2026: Hướng dẫn nền tảng hiện tại của OpenAI tập trung việc phát triển API theo các project, hỗ trợ service account theo project và quyền key bị giới hạn, khuyến nghị xử lý key an toàn ở phía server, và định vị Responses API là giao diện chính cho các quy trình làm việc agentic và đa phương thức mới. Hãy xác minh quyền truy cập model và các giới hạn hiện tại trong tài khoản của bạn trước khi triển khai production.
The Short Version
Hãy dùng trình tự này cho một sản phẩm đa mô hình mới:
- Tạo các OpenAI project riêng biệt cho development, staging và production.
- Sử dụng một service account theo project hoặc một key project có phạm vi chặt chẽ cho workload phía server.
- Giữ secrets trên server và ngoài source control, trình duyệt, và ứng dụng di động.
- Chọn Responses API hoặc Chat Completions dựa trên các tính năng mà ứng dụng của bạn thực sự sử dụng.
- Kiểm thử riêng khả năng sẵn có của model, structured outputs, tools, streaming, và đầu vào đa phương thức.
- Đo giới hạn tốc độ, timeout, retry, độ trễ, và chi phí cho mỗi tác vụ thành công.
- Đưa base URL, key, và model của nhà cung cấp vào cấu hình.
- Chỉ thêm nhà cung cấp thứ hai sau khi bạn đã có bộ đánh giá chung và một đường lùi (rollback).
Mục tiêu không chỉ là tạo ra một request thành công. Mục tiêu là làm cho quyền truy cập có thể quản trị được và có thể di chuyển được.
What OpenAI API Access Means in Production
Quyền truy cập production có sáu lớp. Nếu bất kỳ lớp nào vẫn còn ngầm định, nó thường sẽ trở thành một sự cố sau này.
| Access layer | Production question | Evidence to capture |
|---|---|---|
| Organization and project | Môi trường và team nào sở hữu workload này? | Project ID, chủ sở hữu, môi trường, chủ sở hữu ngân sách |
| Credential | Máy hoặc dịch vụ nào được phép gọi API? | Service account hoặc project key, phạm vi quyền, người chịu trách nhiệm xoay vòng |
| Endpoint | Ứng dụng phụ thuộc vào giao diện API nào? | Responses, Chat Completions, Realtime, embeddings, image, hoặc endpoint khác |
| Model | Tác vụ yêu cầu những capability và giới hạn nào? | Model ID, hỗ trợ tool, modalities, nhu cầu context, hợp đồng đầu ra |
| Operations | Điều gì xảy ra dưới tải cao hoặc khi lỗi một phần? | Kiểm thử rate-limit, chính sách retry, timeout, hành vi hàng đợi, request ID |
| Portability | Workload có thể chuyển đi hoặc chuyển sang fallback nhanh đến mức nào? | Công tắc cấu hình, kiểm thử tương thích, điểm đánh giá, quy trình rollback |
Ma trận truy cập này hữu ích hơn một danh sách API key. Nó gắn từng thông tin xác thực với một workload, từng workload với một hợp đồng, và từng hợp đồng với một kế hoạch vận hành.
Bước 1: Tách các Project theo Môi trường
Các project của OpenAI cung cấp một ranh giới cho API key, service account, mức sử dụng, quyền truy cập mô hình, rate limit, và ngân sách. Điều đó khiến project trở thành điểm khởi đầu phù hợp để tách development, staging, và production.
Một cấu trúc thực tế là:
| Project | Người dùng điển hình | Loại thông tin xác thực | Mục đích chính |
|---|---|---|---|
| Development | Các kỹ sư cá nhân và các job kiểm thử CI | Project key cá nhân hoặc key tự động hóa bị giới hạn | Phát triển cục bộ và các thử nghiệm rủi ro thấp |
| Staging | CI/CD và các dịch vụ tiền production | Service account của project | Kiểm thử tải, kiểm thử tích hợp, ứng viên phát hành |
| Production | Chỉ các dịch vụ backend đã triển khai | Service account của project với quyền tối thiểu | Lưu lượng khách hàng |
Không dùng chung một production key cho laptop, CI, staging, và nhiều dịch vụ. Thông tin xác thực dùng chung khiến việc xoay vòng trở nên gián đoạn và gây khó khăn khi truy vết mức sử dụng bất thường.
OpenAI mô tả project service account là các danh tính có phạm vi theo project. Khi một service account được tạo, secret của nó chỉ hiển thị một lần, vì vậy hãy lưu ngay vào secrets manager của bạn. OpenAI cũng hỗ trợ các quyền key như All, Restricted, và Read Only; hãy dùng quyền hẹp nhất tương thích với workload.
Bước 2: Giữ API Key ở Phía Server
Một OpenAI API key là bí mật, không phải là mã định danh ứng dụng. Tuyệt đối không hiển thị nó trong JavaScript trình duyệt, gói ứng dụng di động, kho lưu trữ công khai, log phía client, hoặc ảnh chụp màn hình hỗ trợ.
Sử dụng biến môi trường hoặc một kho bí mật được quản lý:
OPENAI_API_KEY="your-project-or-service-account-key"
OPENAI_MODEL="your-validated-model-id"
OPENAI_BASE_URL="https://api.openai.com/v1"
Sau đó tạo client trong một module phía server:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
Base URL nên được đặt trong cấu hình ngay cả khi bạn chỉ dùng OpenAI hiện tại. Quyết định nhỏ này giúp các proxy staging, hạ tầng theo khu vực, và định tuyến tương thích OpenAI trong tương lai dễ kiểm thử hơn mà không cần sửa mọi điểm gọi.
Chính sách quản lý key tối thiểu
- Chỉ định một người chịu trách nhiệm cho từng thông tin xác thực production.
- Ghi lại dịch vụ và môi trường sử dụng nó.
- Lưu nó trong secrets manager, không phải trong tài liệu dùng chung.
- Xoay vòng theo lịch và ngay sau khi nghi ngờ bị lộ.
- Xóa các key không còn dùng và quyền truy cập của thành viên đã rời nhóm.
- Cảnh báo về mức sử dụng và thay đổi chi tiêu bất thường.
- Tránh nhúng key vào hình ảnh, ticket, sự kiện phân tích, hoặc lỗi ứng dụng.
Hướng dẫn an toàn key của OpenAI cũng khuyến nghị không bao giờ commit key vào repository và dùng biến môi trường thay vì hardcode chúng.
Bước 3: Chọn Giao diện API Trước khi Chọn Mô hình
Lựa chọn mô hình nhận được nhiều sự chú ý nhất, nhưng việc chọn endpoint thường tạo ra chi phí di chuyển lớn hơn.
Tài liệu hiện tại của OpenAI khuyến nghị Responses API cho các dự án mới cần công cụ tích hợp sẵn, đầu vào đa phương thức hoặc quy trình làm việc kiểu tác nhân. Chat Completions vẫn hữu ích khi ứng dụng của bạn đã có tích hợp dựa trên message ổn định hoặc cần khả năng tương thích rộng với các client và gateway theo kiểu OpenAI.
| Yêu cầu | Bắt đầu với | Lưu ý khi di chuyển |
|---|---|---|
| Quy trình tác nhân mới | Responses API | Xác thực hành vi của công cụ, cách xử lý trạng thái và các hợp đồng đầu ra |
| Công cụ OpenAI tích hợp sẵn | Responses API | Xác nhận mô hình đã chọn và tài khoản đều hỗ trợ từng công cụ |
Tích hợp messages hiện có |
Chat Completions | Giữ nguyên nếu ổn định; chỉ chuyển đổi cho một khả năng cụ thể, không phải theo xu hướng |
| Khả năng di động client giữa các nhà cung cấp | Chat Completions hoặc một lớp tương thích đã được kiểm thử | Khả năng tương thích thay đổi theo nhà cung cấp và tham số |
| Tương tác giọng nói độ trễ thấp | Realtime API | Coi vận chuyển, vòng đời phiên và xử lý âm thanh là các bài kiểm thử riêng biệt |
| Embeddings, ảnh hoặc công việc theo từng phương thức khác | Endpoint phù hợp | Đừng giả định rằng một bài kiểm thử chat đơn giản chứng minh được một endpoint khác |
Kiến trúc đa mô hình có thể sử dụng nhiều hơn một giao diện. Quy tắc quan trọng là xác định rõ hợp đồng của từng workload thay vì che giấu hành vi không tương thích sau một hàm generate() chung chung.
Step 4: Chạy Kiểm tra Khởi động Truy cập
Bắt đầu với request phía server nhỏ nhất có thể để chứng minh xác thực, quyền truy cập endpoint và quyền truy cập mô hình.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
response = client.responses.create(
model=os.environ["OPENAI_MODEL"],
input="Return exactly: access-ok",
)
print(response.output_text)
Đối với một client Chat Completions hiện có:
response = client.chat.completions.create(
model=os.environ["OPENAI_MODEL"],
messages=[
{"role": "user", "content": "Return exactly: access-ok"}
],
)
print(response.choices[0].message.content)
Đừng xem đây là bài kiểm thử tích hợp đầy đủ. Nó chỉ chứng minh một đường đi hẹp.
Ghi lại:
- Mã trạng thái HTTP và kết quả ứng dụng đã chuẩn hóa
- ID mô hình được yêu cầu và ID mô hình được trả về, khi có sẵn
- ID request hoặc mã định danh trace
- Độ trễ và thời gian chờ
- Mức sử dụng đầu vào và đầu ra
- Project và môi trường
- Phiên bản SDK
- Số lần retry
Step 5: Xây dựng Ma trận Kiểm thử Khả năng
Tên mô hình thay đổi nhanh hơn các yêu cầu production. Hãy kiểm thử khả năng, không phải nhãn tiếp thị.
Tạo một hàng cho mỗi workload:
| Khối lượng công việc | Khả năng cần thiết | Điều kiện đạt | Hành vi khi thất bại hoặc dự phòng |
|---|---|---|---|
| Phân loại hỗ trợ | Đầu ra có cấu trúc | Lược đồ hợp lệ trên các ticket đại diện | Thử lại một lần, sau đó đưa vào hàng đợi để xem xét |
| Trợ lý nghiên cứu | Gọi công cụ và trích dẫn | Gọi đúng công cụ và ánh xạ nguồn chính xác | Sử dụng phản hồi dự phòng không bật tìm kiếm |
| Trích xuất tài liệu | Đầu vào tệp hoặc hình ảnh | Các trường bắt buộc đạt ngưỡng độ chính xác | Chuyển sang mô hình thị giác mạnh hơn |
| Chat với khách hàng | Streaming | Token đầu tiên và toàn bộ phản hồi đáp ứng SLO độ trễ | Chuyển sang mô hình không streaming hoặc mô hình dự phòng |
| Tạo mã | Ngữ cảnh dài và tuân thủ chỉ dẫn | Bộ kiểm thử chạy qua | Leo thang sang mô hình chất lượng cao hơn |
Với mỗi mô hình ứng viên, hãy kiểm thử cùng một bộ prompt và cùng một bộ quy tắc chấm điểm. Bao gồm các đầu vào lỗi định dạng, ngữ cảnh trống, ngữ cảnh dài, timeout và lỗi của nhà cung cấp. Một prompt demo thành công không chứng minh được khả năng tương thích với production.
Các chỉ số hữu ích gồm:
- tỷ lệ thành công của tác vụ
- tỷ lệ phản hồi hợp lệ theo schema
- tỷ lệ gọi công cụ thành công
- p50 và p95 độ trễ
- tỷ lệ retry
- chi phí trên mỗi tác vụ thành công
- tỷ lệ chuyển sang người xử lý
Đây là cầu nối giữa quyền truy cập OpenAI API và định tuyến đa mô hình: việc định tuyến nên dựa trên hiệu năng khối lượng công việc được đo lường, chứ không phải sở thích cố định đối với một nhà cung cấp.
Step 6: Lập kế hoạch cho Giới hạn Tốc độ và Các mức Sử dụng
Giới hạn tốc độ của OpenAI có thể áp dụng theo các chiều như số lượng request và token, và giới hạn thay đổi theo mô hình và cấp tài khoản. Hãy kiểm tra trang giới hạn hiện tại cho tổ chức và mô hình của bạn trước khi thiết lập concurrency cho production.
Client của bạn nên phân biệt ít nhất bốn nhóm lỗi:
| Nhóm lỗi | Phản hồi điển hình | Hành động đúng |
|---|---|---|
| Xác thực hoặc quyền | 401 hoặc 403 | Dừng retry, kiểm tra project, key và phạm vi quyền |
| Giới hạn tốc độ | 429 | Giảm tốc với jitter, giảm concurrency hoặc đưa công việc vào hàng đợi |
| Lỗi nhà cung cấp/server | 5xx | Retry một số lần có giới hạn, sau đó dùng fallback hoặc đưa vào hàng đợi |
| Yêu cầu không hợp lệ | 4xx | Sửa yêu cầu; không tạo ra bão retry |
Sử dụng exponential backoff với jitter và số lần thử tối đa. Đặt một ngân sách thời gian tổng cho toàn bộ thao tác, không chỉ cho từng cuộc gọi HTTP. Nếu không, ba lần retry dài có thể vượt quá SLO hướng tới người dùng.
Với công việc không đồng bộ hoặc phù hợp theo lô, hàng đợi có thể hấp thụ các giới hạn tạm thời. Với công việc tương tác, một mô hình dự phòng đã được xác thực có thể tốt hơn. Đó là các chế độ vận hành khác nhau và nên có chính sách retry khác nhau.
Step 7: Thiết kế Ranh giới Đa mô hình
Có hai cách phổ biến để thêm nhiều mô hình hơn.
Option A: Tích hợp trực tiếp với nhà cung cấp
Sử dụng các SDK gốc và thông tin xác thực riêng cho từng nhà cung cấp.
Cách này phù hợp khi:
- bạn cần các tính năng riêng của nhà cung cấp ngay lập tức;
- đội ngũ của bạn có thể quản lý nhiều tài khoản thanh toán và thông tin xác thực;
- bạn muốn có quyền truy cập sớm nhất vào các khả năng gốc của từng nhà cung cấp;
- bạn sẵn sàng tự chuẩn hóa lỗi, mức sử dụng, cơ chế thử lại và telemetry.
Tùy chọn B: Một gateway tương thích OpenAI
Sử dụng một base URL tương thích duy nhất và chọn model thông qua cấu hình hoặc chính sách định tuyến.
Đây là lựa chọn phù hợp khi:
- nhiều workload dùng chung mẫu client của OpenAI;
- bạn muốn có một lớp truy cập, thanh toán, quota và sử dụng duy nhất;
- bạn cần đánh giá model nhanh hơn và thử nghiệm phương án dự phòng;
- việc quản lý tài khoản nhà cung cấp đang trở thành gánh nặng vận hành.
Flatkey cung cấp một base URL tương thích OpenAI tại https://router.flatkey.ai/v1. Với một workload tương thích, ranh giới client có thể giữ ổn định trong khi key, base URL và model được chuyển vào cấu hình.
FLATKEY_API_KEY="your-flatkey-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="your-validated-flatkey-model-id"
client = OpenAI(
api_key=os.environ["FLATKEY_API_KEY"],
base_url=os.environ["OPENAI_BASE_URL"],
)
“Tương thích OpenAI” không có nghĩa là mọi endpoint và tham số đều hoạt động giống hệt. Hãy chạy lại ma trận năng lực cho streaming, đầu ra có cấu trúc, tools, đầu vào đa phương thức, phản hồi lỗi, các trường usage và timeout trước khi chuyển lưu lượng production.
Để có trình tự migration thực hành, hãy dùng danh sách kiểm tra migration cho API gateway tương thích OpenAI. Để kiểm thử ở cấp độ model, hãy dùng quy trình kiểm thử prompt đa mô hình.
Bước 8: Triển khai với staging, shadow test và canary
Hãy triển khai theo từng giai đoạn ngay cả khi đường đi mới vượt qua mọi đánh giá ngoại tuyến.
- Staging: chạy lưu lượng đại diện với mức đồng thời và timeout giống môi trường production.
- Shadow: sao chép các request đủ điều kiện sang đường đi ứng viên mà không dùng phản hồi của nó cho khách hàng.
- Canary: gửi một tỷ lệ nhỏ lưu lượng trực tiếp đến ứng viên.
- Mở rộng: chỉ tăng lưu lượng khi tỷ lệ thành công, độ trễ và chi phí vẫn nằm trong ngưỡng.
- Rollback: khôi phục key, base URL và model trước đó thông qua cấu hình.
Xác định các ngưỡng rollback trước khi phát hành. Ví dụ bao gồm:
- tỷ lệ schema hợp lệ giảm xuống dưới mức nền;
- độ trễ p95 vượt quá SLO của workload;
- tỷ lệ retry hoặc tỷ lệ 429 tăng vượt mức trần đã thỏa thuận;
- tỷ lệ thành công của tác vụ giảm trên một phân khúc khách hàng được bảo vệ;
- chi phí cho mỗi tác vụ thành công vượt ngưỡng ngân sách;
- một tool hoặc modality bắt buộc bị lỗi.
Việc rollback phải có thể được thực hiện bởi kỹ sư trực on-call mà không cần triển khai code.
Danh sách kiểm tra truy cập OpenAI API sẵn sàng cho production
Danh tính và secrets
- Môi trường development, staging và production sử dụng các dự án riêng biệt hoặc các ranh giới tương đương.
- Production sử dụng một service account của dự án hoặc khóa dự án với phạm vi tối thiểu.
- Bí mật được lưu trữ phía máy chủ trong một secrets manager.
- Chủ sở hữu khóa, dịch vụ, môi trường, ngày tạo và quy trình xoay vòng được ghi chép lại.
- Khóa không xuất hiện trong kho lưu trữ, gói trình duyệt, ứng dụng di động, log và ticket.
Hợp đồng API
- Việc lựa chọn endpoint được ghi chép theo từng workload.
- Quyền truy cập model hiện tại được xác minh trong dự án đích.
- Các công cụ, modality, structured output và streaming bắt buộc được kiểm thử độc lập.
- Hành vi của SDK và API được cố định hoặc ghi lại để đảm bảo khả năng tái lập.
- Các trường riêng của nhà cung cấp được tách biệt khỏi logic ứng dụng dùng chung.
Độ tin cậy và chi phí
- Hành vi của 401/403, 429, 4xx, 5xx và timeout được kiểm thử.
- Việc retry sử dụng exponential backoff, jitter, giới hạn số lần thử và ngân sách thời gian tổng.
- Usage, độ trễ, request ID, lỗi và chi phí đều có thể quan sát được.
- Đồng thời đã được kiểm thử theo các giới hạn hiện tại của dự án.
- Chi phí được đo trên mỗi tác vụ thành công, không chỉ theo token.
Sẵn sàng cho đa mô hình
- Base URL, API key và model là các giá trị cấu hình.
- Các model ứng viên sử dụng một bộ đánh giá đại diện duy nhất.
- Quy tắc fallback phụ thuộc vào từng workload.
- Quy trình staging, shadow, canary và rollback được ghi chép lại.
- Khả năng tương thích của gateway được kiểm thử cho mọi tính năng bắt buộc.
Câu hỏi thường gặp
Tôi có cần một tài khoản OpenAI cho mỗi developer không?
Developer có thể được thêm vào organization và dự án liên quan với các vai trò phù hợp. Các workload production nên sử dụng một service account của dự án hoặc thông tin xác thực của dự án riêng thay vì khóa cá nhân của một cá nhân.
Sản phẩm đa mô hình nên dùng Responses API hay Chat Completions?
Hãy dùng Responses API cho các workflow OpenAI-native mới cần tính năng agentic, công cụ tích hợp sẵn hoặc hành vi multimodal. Giữ Chat Completions khi nó khớp với một hợp đồng ổn định hiện có hoặc khi khả năng tương thích với OpenAI-compatible là ưu tiên. Dù theo cách nào, hãy kiểm thử chính xác các năng lực bạn cần.
Tôi có thể đặt OpenAI API key trong ứng dụng frontend không?
Không. Hãy định tuyến yêu cầu qua backend của bạn để key vẫn được giữ bí mật và bạn có thể thực thi xác thực, quota, logging và kiểm soát lạm dụng.
Chỉ một lần gọi API thành công có chứng minh được quyền truy cập production không?
Không. Nó chỉ chứng minh rằng một key, endpoint, model và request đã hoạt động một lần. Sẵn sàng cho production còn đòi hỏi kiểm tra quyền, kiểm thử năng lực, hành vi giới hạn tốc độ, khả năng quan sát, đo lường chi phí và rollback.
Khi nào tôi nên thêm một API gateway?
Hãy thêm một gateway khi việc quản lý các key nhà cung cấp riêng biệt, billing, quota, retry và usage log bắt đầu làm chậm việc phát hành sản phẩm — hoặc khi bạn cần kiểm thử chéo nhiều model và định tuyến fallback có thể lặp lại. Hãy giữ quyền truy cập trực tiếp từ nhà cung cấp khi các tính năng nguyên bản của nhà cung cấp có ý nghĩa chiến lược và đội ngũ của bạn có thể vận hành các tích hợp bổ sung.
Xây dựng quyền truy cập có thể phát triển
Thiết lập OpenAI API tốt nhất không phải là thiết lập có ít trường cấu hình nhất. Đó là thiết lập làm cho quyền sở hữu, quyền truy cập, hợp đồng workload, giới hạn và rollback trở nên rõ ràng.
Bắt đầu với quyền truy cập OpenAI trực tiếp nếu đó là tất cả những gì sản phẩm cần. Đặt khóa, base URL và model sau một lớp cấu hình duy nhất. Xây dựng ma trận kiểm thử năng lực trước khi thêm nhà cung cấp. Sau đó, nếu vận hành đa nhà cung cấp trở thành nút thắt, hãy chuyển các workload tương thích sang một lớp định tuyến hợp nhất mà không làm mất các bài kiểm thử đã chứng minh chúng hoạt động.
Flatkey cung cấp cho các nhóm đa mô hình một base URL tương thích OpenAI duy nhất, một khóa duy nhất và các kiểm soát sử dụng tập trung. Xem danh sách model được truy cập và giá hiện tại, sau đó làm theo hướng dẫn bắt đầu tích hợp Flatkey để chạy bài kiểm thử được kiểm soát đầu tiên của bạn.
