AI Agent Deployment: Triển khai AI Agent với FastAPI và Docker

Đó là lúc AI Agent Deployment trở thành một bước quan trọng trong quy trình phát triển AI Engineering. Trong bài viết này, MCNA Technology School sẽ hướng dẫn cách đóng gói một AI Agent thành REST API bằng FastAPI, sau đó container hóa ứng dụng bằng Docker để chuẩn bị cho quá trình triển khai.

1. AI Agent Deployment là gì?

AI Agent Deployment là quá trình đưa Agent từ môi trường phát triển sang môi trường mà người dùng hoặc các hệ thống khác có thể truy cập. Quá trình này không chỉ bao gồm việc chạy mô hình AI, mà còn liên quan đến API, cấu hình, bảo mật, logging và khả năng vận hành.

Ví dụ, một doanh nghiệp có AI Agent hỗ trợ phân tích dữ liệu bán hàng. Ban đầu, nhân viên có thể chạy Agent trực tiếp trong một file Python. Nhưng nếu muốn tích hợp Agent vào dashboard hoặc hệ thống quản lý nội bộ, doanh nghiệp cần cung cấp một API để các ứng dụng gửi câu hỏi và nhận kết quả.

Những thành phần cơ bản

• AI Agent: Thành phần tiếp nhận yêu cầu, xử lý thông tin và có thể sử dụng LLM hoặc các công cụ bên ngoài.
• FastAPI: Framework Python dùng để xây dựng API cho ứng dụng.
• Docker: Công cụ đóng gói ứng dụng cùng các thành phần cần thiết vào container.
• Environment variables: Nơi cung cấp cấu hình như API key và các thông số môi trường.
• Monitoring và logging: Giúp theo dõi hoạt động, phát hiện lỗi và hỗ trợ bảo trì.

2. Kiến trúc triển khai AI Agent

Ở mô hình đơn giản, ứng dụng phía người dùng gửi yêu cầu đến API. FastAPI tiếp nhận và kiểm tra dữ liệu đầu vào, sau đó chuyển yêu cầu đến logic của Agent. Agent xử lý yêu cầu và trả kết quả về cho API để phản hồi dưới dạng JSON.

Website / Internal System
          |
          v
      REST API
      FastAPI
          |
          v
   AI Agent Logic
          |
          v
  LLM / RAG / Tools
          |
          v
      JSON Response

Docker được sử dụng để đóng gói ứng dụng và các thư viện cần thiết. Container sau đó có thể chạy trên máy chủ hoặc một nền tảng hỗ trợ container. Cách tiếp cận này giúp môi trường chạy ứng dụng nhất quán hơn giữa máy phát triển và môi trường triển khai.

Tham khảo: FastAPI – Deploying with Docker và Docker – Python Guide.

3. Xây dựng AI Agent API bằng FastAPI

Trước tiên, hãy tạo một thư mục dự án với cấu trúc sau:

ai-agent-api/
├── app/
│   └── main.py
├── requirements.txt
├── Dockerfile
└── .dockerignore

Bước 1: Cài đặt thư viện

Tạo file requirements.txt:

fastapi
uvicorn[standard]

Cài đặt các thư viện trong môi trường Python của dự án:

python -m pip install -r requirements.txt

Trong dự án thực tế, nên sử dụng môi trường ảo và khóa phiên bản các thư viện đã kiểm thử để hạn chế sự khác biệt giữa các lần triển khai.

Bước 2: Viết logic Agent và API endpoint

Tạo file app/main.py. Ví dụ dưới đây sử dụng logic xử lý đơn giản để minh họa cách kết nối Agent với API. Đây chưa phải Agent có khả năng suy luận bằng LLM; bạn có thể thay hàm run_agent() bằng logic Agent thực tế của mình.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(
    title="AI Agent API",
    version="1.0.0"
)


class AgentRequest(BaseModel):
    question: str = Field(min_length=1, max_length=2000)


class AgentResponse(BaseModel):
    answer: str


def run_agent(question: str) -> str:
    return f"Agent đã tiếp nhận yêu cầu: {question}"


@app.get("/health")
def health_check():
    return {"status": "ok"}


@app.post("/agent", response_model=AgentResponse)
def invoke_agent(request: AgentRequest):
    answer = run_agent(request.question)
    return AgentResponse(answer=answer)

Trong ví dụ này:

• GET /health cung cấp endpoint kiểm tra trạng thái cơ bản của ứng dụng.
• POST /agent nhận câu hỏi và trả kết quả của Agent.
• Pydantic kiểm tra cấu trúc và giới hạn độ dài đầu vào.
• run_agent() tách biệt logic nghiệp vụ khỏi tầng API, giúp dễ thay thế và kiểm thử.

Bước 3: Chạy và kiểm thử API trên máy cá nhân

Tại thư mục gốc của dự án, chạy lệnh:

uvicorn app.main:app --reload

Mở địa chỉ http://127.0.0.1:8000/docs để sử dụng giao diện Swagger UI do FastAPI tạo tự động.

Chọn endpoint POST /agent, nhấn Try it out và gửi dữ liệu:

{
  "question": "Phân tích doanh thu tháng này"
}

Với logic demo hiện tại, API sẽ trả về câu trả lời xác nhận yêu cầu. Khi tích hợp một LLM hoặc Agent framework, bạn cần bổ sung logic gọi mô hình, xử lý lỗi từ nhà cung cấp và kiểm soát thời gian chờ.

4. Đóng gói ứng dụng bằng Docker

Chạy được API trên máy cá nhân chưa đảm bảo rằng ứng dụng có thể hoạt động giống nhau trên máy chủ khác. Docker giúp đóng gói mã nguồn, thư viện và cấu hình chạy cần thiết vào một container image có thể triển khai ở nhiều môi trường hỗ trợ Docker.

Bước 1: Tạo Dockerfile

Tạo file Dockerfile tại thư mục gốc:

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Ý nghĩa của các thành phần chính:

• FROM chọn image Python làm nền tảng.
• WORKDIR thiết lập thư mục làm việc bên trong container.
• COPY đưa file cần thiết vào image.
• RUN cài đặt các thư viện phụ thuộc.
• EXPOSE mô tả cổng mà ứng dụng sử dụng.
• CMD xác định lệnh chạy API khi container khởi động.

Ví dụ này ưu tiên tính dễ hiểu cho người mới bắt đầu. Khi triển khai production, nên đánh giá việc pin phiên bản thư viện, sử dụng image đáng tin cậy, chạy bằng user không có đặc quyền và áp dụng quy trình quét lỗ hổng cho image.

Bước 2: Tạo file .dockerignore

Tạo file .dockerignore để tránh đưa các file không cần thiết hoặc dữ liệu nhạy cảm vào build context:

.git
.venv
__pycache__
*.pyc
.env
.env.*
!.env.example

Không đưa API key, mật khẩu hoặc file chứa thông tin bí mật vào Docker image. File .env cần được quản lý bên ngoài image và không đưa lên Git repository.

Bước 3: Build và chạy container

Build image:

docker build -t ai-agent-api .

Khởi chạy container:

docker run --rm -p 8000:8000 ai-agent-api

Sau khi container khởi động, mở http://localhost:8000/docs để kiểm tra API. Bạn cũng có thể gửi yêu cầu đến endpoint health check tại http://localhost:8000/health.

5. Quản lý API key và cấu hình môi trường

Nếu Agent sử dụng OpenAI API hoặc một nhà cung cấp LLM khác, ứng dụng thường cần API key để xác thực. Không nên ghi trực tiếp API key vào mã nguồn hoặc Dockerfile, vì thông tin này có thể bị lộ khi chia sẻ repository hay image.

Trong ứng dụng thực tế, hãy đọc API key từ environment variable. Ví dụ:

import os

api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    raise RuntimeError("OPENAI_API_KEY chưa được cấu hình")

Khi chạy container trên máy cá nhân, có thể truyền biến môi trường từ bên ngoài:

docker run --rm \
  -p 8000:8000 \
  -e OPENAI_API_KEY \
  ai-agent-api

Lệnh trên truyền giá trị biến môi trường đã có trong terminal vào container. Cách quản lý secret trên nền tảng production cần tuân theo cơ chế bảo mật của nền tảng đó, chẳng hạn secret manager hoặc secret injection. Không chia sẻ API key trong ảnh chụp màn hình, log hay tài liệu công khai.

6. Những điều cần kiểm tra trước khi đưa AI Agent lên production

Đóng gói thành API và chạy bằng Docker mới chỉ là một phần của quá trình triển khai. Một Agent được sử dụng trong môi trường thật cần được kiểm soát về độ ổn định, bảo mật và chi phí.

Ngoài ra, endpoint /health trong ví dụ chỉ xác nhận ứng dụng phản hồi. Với hệ thống phụ thuộc vào cơ sở dữ liệu, vector database hoặc nhà cung cấp LLM, cần thiết kế thêm cơ chế kiểm tra dependency phù hợp, tránh để health check tạo ra lượng truy vấn tốn kém hoặc gây quá tải.

7. Các lỗi phổ biến khi triển khai AI Agent

Lỗi 1: API chạy được ở local nhưng không truy cập được trong container

Nguyên nhân thường gặp là ứng dụng chỉ bind vào địa chỉ loopback. Khi chạy trong Docker, cần cho server lắng nghe trên 0.0.0.0 và ánh xạ cổng bằng tham số -p.

Lỗi 2: Container khởi động nhưng gọi LLM thất bại

Hãy kiểm tra API key, quyền truy cập của key, cấu hình mạng, giới hạn sử dụng của nhà cung cấp và thông báo lỗi trong log. Không nên đưa secret trực tiếp vào mã nguồn để xử lý nhanh lỗi này.

Lỗi 3: Request mất quá nhiều thời gian

Agent có thể thực hiện nhiều bước như gọi LLM, truy vấn dữ liệu và sử dụng tools. Cần đặt timeout phù hợp, theo dõi từng bước xử lý và cân nhắc tác vụ chạy nền nếu quy trình kéo dài. Không nên tự động retry các thao tác có tác dụng phụ nếu chưa có cơ chế idempotency.

Lỗi 4: Chạy nhiều container nhưng kết quả không nhất quán

Không nên phụ thuộc vào biến toàn cục hoặc bộ nhớ trong một process để lưu trạng thái hội thoại lâu dài. Khi cần chia sẻ trạng thái giữa nhiều instance, hãy sử dụng kho lưu trữ phù hợp và thiết kế rõ vòng đời dữ liệu.

8. Lộ trình mở rộng từ demo đến hệ thống AI thực tế

Sau khi triển khai được API cơ bản, bạn có thể nâng cấp hệ thống theo từng giai đoạn:

• Giai đoạn 1: Thay logic demo bằng Agent sử dụng LLM.
• Giai đoạn 2: Kết nối RAG hoặc các công cụ nghiệp vụ.
• Giai đoạn 3: Bổ sung xác thực, quản lý secret và giới hạn truy cập.
• Giai đoạn 4: Thêm logging, tracing, đánh giá chất lượng và theo dõi chi phí.
• Giai đoạn 5: Tự động hóa kiểm thử, build image và triển khai thông qua CI/CD.

Không phải dự án nào cũng cần Kubernetes hoặc kiến trúc phân tán ngay từ đầu. Với một ứng dụng nhỏ, một container và một máy chủ có thể đủ để kiểm chứng ý tưởng. Hãy lựa chọn kiến trúc dựa trên tải thực tế, yêu cầu sẵn sàng, mức độ bảo mật và khả năng vận hành của đội ngũ.

Kết luận

AI Agent Deployment là bước chuyển từ một chương trình AI chạy trên máy cá nhân thành một dịch vụ có thể tích hợp vào hệ thống thực tế. FastAPI giúp xây dựng giao diện API rõ ràng, trong khi Docker giúp đóng gói môi trường chạy ứng dụng nhất quán hơn.

Tuy nhiên, triển khai thành công không chỉ có nghĩa là API trả về kết quả. Một hệ thống production còn cần bảo vệ thông tin xác thực, kiểm soát đầu vào, xử lý lỗi, giám sát hiệu năng và giới hạn quyền của Agent. Đây là những yếu tố giúp ứng dụng AI dễ bảo trì và đáng tin cậy hơn khi mở rộng.

Học thêm về AI và Data tại MCNA Technology School

Nếu bạn muốn xây dựng nền tảng Python, phân tích dữ liệu và ứng dụng AI vào các bài toán thực tế, có thể tham khảo các chương trình học tại MCNA Technology School:

• Combo 5 khóa AI và Power BI
• Combo Python