Thiết lập cấu trúc dự án và Dockerfile tối ưu
Chúng ta cần tạo một Dockerfile chuẩn cho ứng dụng Python AI, ưu tiên hình ảnh nhỏ gọn (slim), tận dụng caching layer để giảm thời gian build, và tách biệt rõ ràng giữa quá trình cài đặt phụ thuộc và chạy ứng dụng.
Đầu tiên, hãy tạo file Dockerfile tại thư mục gốc của dự án. File này sẽ sử dụng Python 3.11-slim để giảm kích thước, cài đặt các công cụ cần thiết cho việc build wheel (như build-essential) chỉ trong lúc build, sau đó xóa chúng đi để giảm kích thước image cuối cùng.
FROM python:3.11-slim
# Cài đặt các công cụ cần thiết cho việc build wheel và xử lý PDF/LLM
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential \
gcc \
libpq-dev \
curl \
&& rm -rf /var/lib/apt/lists/*
# Tạo người dùng không root để bảo mật
RUN useradd -m -u 1000 appuser
# Thiết lập thư mục làm việc
WORKDIR /app
# Sao chép file yêu cầu trước để tận dụng Docker layer caching
COPY requirements.txt .
# Cài đặt các thư viện Python (LangGraph, CrewAI, LangChain, v.v.)
RUN pip install --no-cache-dir -r requirements.txt
# Sao chép toàn bộ mã nguồn vào container
COPY . .
# Chuyển quyền sở hữu thư mục /app cho người dùng appuser
RUN chown -R appuser:appuser /app
# Chuyển sang người dùng không root
USER appuser
# Đường dẫn đến script khởi động (sẽ tạo ở bước sau)
CMD ["python", "startup.py"]
Kết quả mong đợi: File Dockerfile được tạo với cấu trúc đa lớp, đảm bảo các lệnh pip cache lại, và giảm thiểu kích thước image bằng cách xóa các gói build tools sau khi cài đặt.
Chuẩn bị file requirements.txt
File requirements.txt cần liệt kê chính xác các phiên bản của LangGraph, CrewAI và các thư viện hỗ trợ để tránh xung đột phụ thuộc.
Tạo file requirements.txt với nội dung sau, bao gồm các gói cốt lõi cho AI Agent:
langchain>=0.1.0
langgraph>=0.0.15
crewai>=0.20.0
langchain-community>=0.0.10
langchain-core>=0.1.0
python-dotenv>=1.0.0
uvicorn>=0.23.0
pydantic>=2.0.0
Kết quả mong đợi: File requirements.txt được tạo, chứa danh sách các thư viện cần thiết để build image.
Quản lý biến môi trường và cấu hình
Tạo file .env mẫu
Để bảo mật API keys và cấu hình LLM, chúng ta không hardcode trực tiếp vào code hay Dockerfile. Thay vào đó, sử dụng file .env và biến môi trường trong container.
Tạo file .env.example (không bao giờ commit file .env thật vào Git) với các biến cần thiết:
LANGCHAIN_API_KEY=your_langchain_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
CREWAI_API_KEY=your_crewai_api_key_here
MODEL_NAME=gpt-4-turbo
AGENT_ROLE=researcher
TARGET_OUTPUT=output.json
Kết quả mong đợi: File .env.example được tạo, giúp đồng nghiệp biết cần cấu hình những biến môi trường nào.
Điều chỉnh Dockerfile để load biến môi trường
Chúng ta sẽ sử dụng .env file trong container để set các biến môi trường khi khởi động, hoặc truyền trực tiếp qua -e khi chạy container. Ở đây, tôi sẽ cấu hình Dockerfile để đọc từ file .env nếu có, nhưng ưu tiên biến môi trường được truyền vào từ bên ngoài.
Cập nhật lại phần cuối của file Dockerfile (thêm lệnh COPY và ENV):
# Sao chép file .env mẫu vào container (nếu có file .env thật trong build context)
COPY .env.example /app/.env
# Thiết lập biến môi trường mặc định (có thể bị override khi chạy)
ENV PYTHONUNBUFFERED=1
ENV LANGCHAIN_TRACING_V2=true
# Giữ nguyên CMD như cũ, script startup.py sẽ load .env
CMD ["python", "startup.py"]
Kết quả mong đợi: Dockerfile được cập nhật để hỗ trợ tải file .env và thiết lập các biến môi trường mặc định cho việc tracing và debug.
Xây dựng kịch bản khởi động (Startup Script)
Tạo script startup.py
Thay vì chạy trực tiếp file main.py, chúng ta cần một script khởi động (startup.py) để kiểm tra biến môi trường, load model, khởi tạo Graph/Agent và xác nhận container đã sẵn sàng (Health Check).
Tạo file startup.py với logic sau: kiểm tra API keys, load environment variables, khởi tạo CrewAI/LangGraph graph, và in log xác nhận.
import os
import sys
import time
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph
from crewai import Agent, Task, Crew
# Load biến môi trường từ file .env nếu tồn tại
load_dotenv()
# Kiểm tra các biến môi trường bắt buộc
required_vars = ["LANGCHAIN_API_KEY", "OPENAI_API_KEY"]
missing_vars = [var for var in required_vars if not os.getenv(var)]
if missing_vars:
print(f"Error: Missing required environment variables: {', '.join(missing_vars)}")
sys.exit(1)
print("Initializing AI Agent Environment...")
# Khởi tạo LLM
llm = ChatOpenAI(model_name=os.getenv("MODEL_NAME", "gpt-4-turbo"))
print(f"LLM initialized: {llm.model_name}")
# Khởi tạo LangGraph (Ví dụ đơn giản)
workflow = StateGraph(dict)
# Thêm node và edge logic ở đây nếu cần
# workflow.add_node("agent", lambda x: x)
# workflow.set_entry_point("agent")
# app = workflow.compile()
print("LangGraph workflow initialized.")
# Khởi tạo CrewAI Agent (Ví dụ)
researcher = Agent(
role="Senior Researcher",
goal="Find the latest AI trends",
backstory="You are an expert in AI research.",
llm=llm,
verbose=True
)
print("CrewAI Agent initialized.")
print("Container is ready to serve requests.")
print("Waiting for external API Gateway or Kubernetes Liveness Probe...")
# Loop vô hạn để giữ container chạy (chỉ dùng cho test, production nên dùng server)
while True:
time.sleep(60)
print("Heartbeat: Agent is alive.")
Kết quả mong đợi: Script startup.py được tạo, thực hiện kiểm tra lỗi API key, khởi tạo các đối tượng Agent và Graph, sau đó giữ container chạy để chờ request.
Build Image và Chạy Container kiểm tra
Build Docker Image
Thực hiện lệnh build để tạo image từ Dockerfile đã viết. Chúng ta đặt tag là ai-agent:latest để dễ quản lý.
Chạy lệnh sau tại thư mục chứa Dockerfile:
docker build -t ai-agent:latest .
Kết quả mong đợi: Quá trình build hoàn thành, hiển thị dòng Successfully built [IMAGE_ID]. Kiểm tra kích thước image bằng docker images | grep ai-agent để đảm bảo không quá lớn (dưới 1GB nếu chỉ có Python libs).
Chạy container với biến môi trường
Chạy container bằng cách truyền biến môi trường trực tiếp qua -e hoặc sử dụng file --env-file. Ở đây tôi dùng -e để minh họa rõ ràng việc truyền key.
Chạy lệnh (thay thế YOUR_KEY_HERE bằng key thật của bạn):
docker run -d \
--name ai-agent-test \
-e LANGCHAIN_API_KEY=YOUR_KEY_HERE \
-e OPENAI_API_KEY=YOUR_KEY_HERE \
-e MODEL_NAME=gpt-4-turbo \
ai-agent:latest
Kết quả mong đợi: Container được tạo và chạy ở chế độ detached (-d), trả về Container ID. Không có lỗi crash ngay lập tức.
Verify kết quả và kiểm tra Log
Kiểm tra trạng thái container và xem log để xác nhận script khởi động đã chạy đúng, API keys đã được load và Agent đã được khởi tạo.
Thực hiện các lệnh sau:
docker ps | grep ai-agent-test
docker logs ai-agent-test
Kết quả mong đợi:
1. docker ps hiển thị trạng thái Up.
2. docker logs hiển thị các dòng log:
- "Initializing AI Agent Environment..."
- "LLM initialized: gpt-4-turbo"
- "LangGraph workflow initialized."
- "CrewAI Agent initialized."
- "Container is ready to serve requests."
Nếu thấy lỗi "Missing required environment variables", hãy kiểm tra lại lệnh docker run hoặc file .env.
Xử lý lỗi thường gặp
Nếu container tự tắt (Exited 137), có thể do thiếu RAM (OOM). Nếu lỗi ModuleNotFoundError, hãy kiểm tra lại requirements.txt và chạy lại docker build --no-cache.
Lệnh để xóa container test sau khi kiểm tra xong:
docker rm -f ai-agent-test
Kết quả mong đợi: Container bị xóa sạch, sẵn sàng cho bước tiếp theo là triển khai lên Kubernetes.
Điều hướng series:
Mục lục: Series: Xây dựng nền tảng AI Agent tự động hóa với LangGraph, CrewAI và Kubernetes
« Phần 3: Tạo hệ thống đa Agent hợp tác với CrewAI
Phần 5: Triển khai Agent lên Kubernetes với Deployment và Service »