Hướng dẫn dùng AI

Đưa mô hình AI thành API web bằng FastAPI

Khi muốn ứng dụng web, ứng dụng điện thoại hay bạn cùng nhóm dùng được mô hình AI của bạn, bạn cần một dịch vụ web đứng giữa: nhận yêu cầu, kiểm tra, gọi mô hình, trả kết quả. FastAPI là thư viện Python làm việc này gọn gàng. Bài này dựng một dịch vụ trợ giảng nhỏ có kiểm dữ liệu, khóa dịch vụ, giới hạn 5 câu hỏi mỗi phút, đổi lỗi thành mã HTTP rõ ràng, và bộ thử chạy không cần mạng.

Ý chính
  • Dịch vụ web đứng giữa người dùng và mô hình: giữ khóa API của mô hình ở máy chủ, kiểm dữ liệu vào, giới hạn số lần gọi, ghi nhật ký.
  • FastAPI dùng Pydantic để kiểm dữ liệu: khai báo kiểu và độ dài, yêu cầu sai sẽ tự nhận mã 422 kèm mô tả lỗi.
  • Mỗi loại lỗi một mã HTTP rõ ràng: 401 sai khóa dịch vụ, 422 dữ liệu sai, 429 quá giới hạn, 502 lỗi khi gọi mô hình, 503 máy chủ chưa cấu hình.
  • Thử bằng TestClient và thay client mô hình bằng client giả, nên bộ thử chạy nhanh, không tốn tiền.

Bài này dựa trên tài liệu chính thức của FastAPI (các trang Request Body, Testing, Testing Dependencies with Overrides), đọc ngày 11/11/2026. Nếu chưa gọi API mô hình lần nào, đọc trước bài gọi API AI bằng Python.

Vì sao cần một dịch vụ đứng giữa

Bạn có một đoạn Python gọi Claude chạy tốt trên máy mình. Giờ muốn trang web của lớp dùng nó. Không thể nhúng khóa API của mô hình vào trang web, vì ai mở trang cũng đọc được khóa và dùng bằng tiền của bạn. Cách đúng là dựng một dịch vụ web trên máy chủ: trình duyệt gửi câu hỏi tới dịch vụ, dịch vụ giữ khóa và gọi mô hình, rồi trả kết quả. Dịch vụ cũng là chỗ đặt các lớp bảo vệ: ai được gọi, gọi bao nhiêu lần, câu hỏi dài tối đa bao nhiêu.

FastAPI là một thư viện Python để làm dịch vụ web, dựa trên chú thích kiểu của Python. Bạn viết hàm bình thường, gắn đường dẫn, khai báo kiểu dữ liệu, và FastAPI lo phần đọc yêu cầu, kiểm dữ liệu, trả JSON, sinh trang tài liệu tự động.

Kiểm dữ liệu bằng Pydantic

Theo trang Request Body của FastAPI, bạn khai báo dữ liệu gửi lên bằng một lớp kế thừa BaseModel của Pydantic. FastAPI đọc thân yêu cầu dạng JSON, chuyển thành đối tượng đúng kiểu, và nếu dữ liệu sai thì trả lỗi rõ ràng chỉ đúng chỗ sai. Trong dịch vụ của bài, câu hỏi là chuỗi dài từ 1 đến 2.000 ký tự; gửi chuỗi rỗng hoặc quá dài đều nhận mã 422. Giới hạn độ dài này cũng là giới hạn chi phí: không ai gửi được một cuốn sách vào mỗi lần gọi.

Câu trả lời cũng được khai báo bằng một lớp: chữ trả lời, số token vào, số token ra. Phía gọi dịch vụ biết chắc định dạng nhận về, và bạn có số token để theo dõi chi phí.

Một yêu cầu qua dịch vụ AI Mỗi lớp chặn một loại lỗi, trả mã HTTP rõ ràng 1. Khóa dịch vụSai hoặc thiếutrả 401 2. Kiểm dữ liệuPydanticsai thì 422 3. Giới hạn5 lần mỗi phútquá thì 429 4. Gọi mô hìnhLỗi thì 502đúng thì JSON Khóa API của mô hình chỉ nằm ở máy chủ
Một yêu cầu qua dịch vụ AI 1. Khóa dịch vụSai hoặc thiếutrả 401 2. Kiểm dữ liệuPydanticsai thì 422 3. Giới hạn5 lần mỗi phútquá thì 429 4. Gọi mô hìnhLỗi thì 502đúng thì JSON Khóa API của mô hình chỉ nằm ở máy chủ
Hình 1. Một yêu cầu đi qua dịch vụ AI, mỗi lớp chặn một loại lỗi và trả mã HTTP rõ ràng: khóa dịch vụ sai hoặc thiếu thì 401; dữ liệu sai theo Pydantic thì 422; quá 5 lần mỗi phút thì 429; gọi mô hình lỗi thì 502, đúng thì trả JSON. Khóa API của mô hình chỉ nằm ở máy chủ.

Dịch vụ trợ giảng

Đoạn code dưới đây có hai đường dẫn. GET /suc-khoe trả trạng thái để công cụ giám sát kiểm dịch vụ còn sống. POST /hoi nhận câu hỏi và trả lời. Phần bảo vệ viết thành các hàm phụ thuộc (dependency) của FastAPI: một hàm đọc khóa dịch vụ trong tiêu đề yêu cầu và so với biến môi trường, sai thì 401; một hàm đếm số lần gọi của mỗi khóa trong 60 giây gần nhất, quá 5 thì 429; một hàm tạo client mô hình, báo 503 nếu máy chủ chưa có khóa mô hình. Lỗi từ thư viện anthropic khi gọi mô hình được đổi thành 502 với lời nhắn ngắn, không lộ chi tiết nội bộ. Mô hình trả về mà không có câu trả lời dùng được (bị cắt vì chạm max_tokens, từ chối, hay không có chữ nào) cũng thành 502, để dịch vụ không bao giờ trả 200 kèm câu trả lời rỗng hoặc dở dang. max_tokens để rộng vì phần suy nghĩ của mô hình cũng tính vào đó.

"""Dịch vụ web nhỏ bọc một lời gọi mô hình AI, viết bằng FastAPI.

- POST /hoi: nhận câu hỏi (kiểm độ dài bằng Pydantic), gọi Claude, trả câu trả lời và số token.
- GET /suc-khoe: kiểm dịch vụ còn sống.
- Khóa của dịch vụ (DICH_VU_KHOA) đặt trong header X-Khoa-Dich-Vu: ai không có khóa thì bị từ chối,
  để người lạ không gọi mô hình bằng tiền của bạn. Khóa API của mô hình chỉ nằm ở máy chủ, không bao giờ gửi cho trình duyệt.
- Giới hạn mỗi khóa 5 câu hỏi mỗi phút (bộ đếm trong bộ nhớ, đủ cho một máy chủ nhỏ).
Cài: python -m pip install fastapi uvicorn anthropic ; chạy: uvicorn dich_vu:app
"""
import os
import time
from collections import defaultdict, deque

from fastapi import Depends, FastAPI, Header, HTTPException
from pydantic import BaseModel, Field

TOI_DA_MOI_PHUT = 5
HE_THONG = "Bạn là trợ giảng Python. Trả lời ngắn gọn bằng tiếng Việt."
gio = time.monotonic
_lich_su = defaultdict(deque)

app = FastAPI(title="Trợ giảng Python")


class YeuCau(BaseModel):
    cau_hoi: str = Field(min_length=1, max_length=2000)


class TraLoi(BaseModel):
    tra_loi: str
    token_vao: int
    token_ra: int


def lay_client():
    if not os.environ.get("ANTHROPIC_API_KEY"):
        raise HTTPException(status_code=503, detail="Máy chủ chưa cấu hình khóa mô hình")
    import anthropic
    return anthropic.Anthropic()


def kiem_khoa(x_khoa_dich_vu: str = Header(default="")):
    khoa = os.environ.get("DICH_VU_KHOA", "")
    if not khoa or x_khoa_dich_vu != khoa:
        raise HTTPException(status_code=401, detail="Sai hoặc thiếu khóa dịch vụ")
    return x_khoa_dich_vu


def gioi_han(khoa: str = Depends(kiem_khoa)):
    bay_gio, ls = gio(), _lich_su[khoa]
    while ls and bay_gio - ls[0] > 60:
        ls.popleft()
    if len(ls) >= TOI_DA_MOI_PHUT:
        raise HTTPException(status_code=429, detail="Quá 5 câu hỏi mỗi phút, thử lại sau")
    ls.append(bay_gio)


@app.get("/suc-khoe")
def suc_khoe():
    return {"trang_thai": "ok"}


@app.post("/hoi", response_model=TraLoi, dependencies=[Depends(gioi_han)])
def hoi(yc: YeuCau, client=Depends(lay_client)):
    try:
        # Haiku 5.5 suy nghĩ trước khi trả lời, và token suy nghĩ tính vào max_tokens dù không hiện ra, nên để rộng chỗ.
        # max_tokens chỉ là mức trần: bạn trả tiền cho số token thật sự sinh ra.
        tl = client.messages.create(model="claude-haiku-5-5", max_tokens=16000, system=HE_THONG,
                                    messages=[{"role": "user", "content": yc.cau_hoi}])
    except Exception as e:  # noqa: BLE001
        if type(e).__module__.startswith("anthropic"):
            raise HTTPException(status_code=502, detail="Không gọi được mô hình, thử lại sau") from e
        raise
    chu = "".join(k.text for k in tl.content if k.type == "text")
    # Không bao giờ trả 200 kèm câu trả lời rỗng hay dở dang.
    if tl.stop_reason in ("max_tokens", "model_context_window_exceeded"):
        raise HTTPException(status_code=502, detail="Câu trả lời bị cắt giữa chừng, thử hỏi ngắn gọn hơn")
    if tl.stop_reason == "refusal" or not chu.strip():
        raise HTTPException(status_code=502, detail="Mô hình không đưa ra câu trả lời, thử hỏi cách khác")
    return TraLoi(tra_loi=chu, token_vao=tl.usage.input_tokens, token_ra=tl.usage.output_tokens)

Chạy dịch vụ bằng uvicorn, rồi mở trang tài liệu tự động mà FastAPI sinh ra để thử gửi câu hỏi ngay trên trình duyệt. Bộ đếm giới hạn trong bài nằm trong bộ nhớ, đủ cho một máy chủ nhỏ chạy một tiến trình; khi chạy nhiều tiến trình hay nhiều máy, cần một chỗ đếm chung.

Thử mà không gọi mô hình thật

Trang Testing của FastAPI hướng dẫn dùng TestClient (dựa trên thư viện HTTPX) để gửi yêu cầu tới ứng dụng ngay trong chương trình thử, không cần chạy máy chủ. Trang Testing Dependencies with Overrides chỉ cách thay một hàm phụ thuộc bằng hàm khác khi thử. Bộ thử đi kèm bài dùng cả hai: thay hàm tạo client mô hình bằng client giả trả câu trả lời cố định, rồi kiểm tra từng trường hợp: sức khỏe, thiếu khóa, sai khóa, câu hỏi rỗng, câu hỏi quá dài, câu trả lời đúng định dạng, lần gọi thứ sáu trong một phút bị chặn và được mở lại sau 60 giây, lỗi thư viện mô hình thành 502, câu trả lời bị cắt hay rỗng thành 502, thiếu khóa mô hình thành 503. Đồng hồ cũng được thay bằng đồng hồ giả để không phải chờ một phút thật.

Thói quen này đáng học từ sớm: mọi thứ gọi ra ngoài (mô hình, cơ sở dữ liệu, dịch vụ khác) nên đi qua một hàm có thể thay khi thử. Bộ thử chạy trong vài giây, không tốn tiền, chạy được mỗi lần sửa code.

Phía gọi dịch vụ dùng thế nào

Người làm giao diện chỉ cần biết ba thứ: địa chỉ của đường dẫn hỏi, khóa dịch vụ đặt ở tiêu đề nào, và hình dạng dữ liệu gửi đi, nhận về. FastAPI tự sinh trang mô tả các điều này từ chính code, nên bạn không phải viết tài liệu riêng và tài liệu không bao giờ lệch với code. Phía gọi xử lý theo mã trả về: 200 thì hiện câu trả lời; 422 thì báo người dùng sửa câu hỏi; 429 thì báo chờ một lát; 502 hoặc 503 thì báo hệ thống đang gặp sự cố. Vì mỗi lỗi có mã riêng, giao diện hiện được thông báo dễ hiểu thay vì một câu chung chung "có lỗi xảy ra".

Một lưu ý về khóa dịch vụ: nếu giao diện chạy trong trình duyệt, khóa đó cũng lộ cho người xem trang. Với ứng dụng công khai, nên thay khóa chung bằng đăng nhập người dùng thật, và đếm giới hạn theo từng người.

Trước khi đưa lên mạng

Vài việc cần làm thêm khi dịch vụ được người khác dùng thật:

  • Khóa và bí mật: đặt bằng biến môi trường hoặc kho bí mật của nơi triển khai, không ghi trong code, không đưa lên GitHub; xem bài giữ khóa API an toàn.
  • Hạn mức chi tiêu: đặt hạn mức ở tài khoản API của mô hình, phòng khi giới hạn phía dịch vụ có lỗ hổng.
  • Thời gian chờ và thử lại: đặt thời gian chờ cho lời gọi mô hình; với lỗi tạm thời, thử lại có giới hạn như trong bài xử lý lỗi khi gọi API AI.
  • Nhật ký: ghi mỗi lần gọi gồm thời gian, khóa dịch vụ, số token, mã lỗi; không ghi nguyên văn câu hỏi nếu có thể chứa thông tin cá nhân.
  • Mã hóa đường truyền: chỉ phục vụ qua HTTPS.

Khi nào cần nhiều hơn

Với câu trả lời dài, dịch vụ nên truyền dần từng đoạn chữ thay vì chờ xong mới trả. Với việc tốn thời gian như xử lý tệp lớn, dịch vụ nên nhận việc, trả mã việc ngay, rồi xử lý nền; người gọi hỏi lại sau. Với mô hình chạy trên máy chủ của bạn (không qua API), cần nạp mô hình một lần khi dịch vụ khởi động thay vì mỗi lần gọi. Mỗi hướng là một bước tiếp theo khi dịch vụ lớn dần.

Cẩn thận
  • Nhúng khóa API của mô hình vào mã trang web hay ứng dụng điện thoại.
  • Không giới hạn độ dài câu hỏi và số lần gọi, để người lạ dùng hết hạn mức.
  • Trả nguyên văn lỗi nội bộ cho người gọi.
  • Bộ thử gọi mô hình thật, tốn tiền và chậm.
  • Ghi nhật ký nguyên văn câu hỏi có thông tin cá nhân.

Câu hỏi thường gặp

FastAPI khác Flask thế nào?

Cả hai đều làm dịch vụ web bằng Python. FastAPI dựa vào chú thích kiểu để tự kiểm dữ liệu và sinh tài liệu; Flask tối giản hơn, phần kiểm dữ liệu bạn tự chọn thư viện.

Có cần học async không?

Không bắt buộc để bắt đầu. Hàm thường chạy được; async có ích khi dịch vụ chờ nhiều lời gọi mạng cùng lúc.

Giới hạn 5 lần mỗi phút có đủ chặn lạm dụng?

Đủ cho ví dụ nhỏ. Dịch vụ thật cần thêm hạn mức theo ngày, theo người dùng, và hạn mức chi tiêu ở phía tài khoản API.

Đưa dịch vụ lên đâu?

Có nhiều dịch vụ đám mây chạy được ứng dụng Python. Chọn nơi cho phép đặt biến môi trường bí mật và có HTTPS sẵn.

Học tiếp

Nếu bạn muốn học Python và AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.

Muốn học bài bản cùng giảng viên?

Khóa AI – Introduction to Machine Learning: nền tảng Máy học từ thuật toán cơ bản đến Neural Networks và LLM, học bằng Python. Học thử buổi 1 miễn phí.

Xem Khóa AI

Nguồn tham khảo

Chia sẻ: Facebook LinkedIn
Nhắn Zalo tư vấnZalo Gọi 0937 401 483