AI Engineer Roadmap: Cách Cấu Trúc Dự Án AI Để Dễ Bảo Trì và Mở Rộng

Dự án AI hiếm khi hỏng ở phần khó. Nó hỏng ở các mối nối: prompt nằm rải trong string, model ID hardcode ở mười hai chỗ, tập eval nằm trong notebook của một người, và trace không đủ để biết request nào tốn 4 USD. Sáu tháng sau, không ai dám đổi model vì không biết cái gì sẽ vỡ.

Cấu trúc dự án tốt không làm AI thông minh hơn. Nó làm cho việc đổi model, đổi prompt và đổi index trở thành một thao tác có kiểm soát thay vì một canh bạc. Dưới đây là cấu trúc cụ thể, lý do của từng thư mục, và một ví dụ chạy được.

Cập nhật 2026

  • Model và giá đổi nhanh hơn code. OpenAI hiện có Astra, Sol, Terra, Luna với giá và ngưỡng khác nhau; Gemini 4 Argon có giá promo hết hạn 2026-11-30. Model ID và giá không được nằm rải trong code.
  • Prompt caching là đòn bẩy chi phí thật: giữ phần đầu byte-ổn định, đặt nội dung thay đổi ở cuối. Cấu trúc prompt ảnh hưởng trực tiếp đến hóa đơn.
  • OTel GenAI vẫn ở trạng thái Development, tên attribute còn đổi. Phải pin phiên bản semantic conventions nếu dựa vào tracing.
  • Eval đã thành công cụ CI: promptfoo 0.125.1, DeepEval 4.3.3, Ragas 0.4.3. Chúng chỉ hữu ích khi dataset và ngưỡng nằm trong repo.

Năm nguyên tắc

  • Prompt là artifact có version, không phải chuỗi trong code. Mỗi phiên bản là một file bất biến; sửa nghĩa là tạo file mới.
  • Eval là hợp đồng, không phải báo cáo. Dataset, metric và ngưỡng nằm trong repo và chạy trong CI.
  • Provider là adapter, không phải lời gọi rải rác. Mọi thứ đi qua một interface, để đổi model là đổi cấu hình.
  • Tool là registry, không phải danh sách viết tay. Mỗi tool có schema, quyền, và giới hạn chi phí.
  • Config là schema, không phải file YAML tự do. Sai kiểu phải fail lúc khởi động, không phải lúc 2 giờ sáng.

Cây thư mục

ai-service/
├── app/
│   ├── cli.py                  # entry point chạy được
│   ├── config.py               # schema cấu hình, đọc env
│   ├── providers/
│   │   ├── base.py             # interface complete/stream
│   │   └── openai_adapter.py   # adapter cụ thể
│   ├── prompts/
│   │   ├── summarize.v1.md     # prompt bất biến
│   │   └── registry.yaml       # id, version, hash, owner
│   ├── tools/
│   │   └── registry.py         # schema + quyền + giới hạn
│   └── tracing.py              # span, token accounting
├── evals/
│   ├── datasets/summarize.jsonl
│   └── run_eval.py
├── tests/
│   ├── test_prompt_contract.py
│   └── test_provider_contract.py
├── migrations/
│   ├── prompts/                # prompt mới kèm eval
│   └── indexes/                # reindex + alias
├── deploy/
├── pyproject.toml
├── uv.lock
└── AGENTS.md

Bốn thư mục làm phần lớn công việc: prompts/ là nguồn sự thật của hành vi; evals/ là nguồn sự thật của chất lượng; providers/ là nơi duy nhất biết tên model; migrations/ là nơi ghi lại các lần đổi. Mọi thứ khác là code thường.

Đừng tạo utils/ rỗng. Nếu một hàm không thuộc module nào, nó thường thuộc providers/ hoặc tools/. Thư mục utils/ là nơi code đi vào và không bao giờ đi ra.

Ví dụ chạy được

Ví dụ tối thiểu nhưng đúng cấu trúc: một prompt file, một adapter, một entry point. Cài openai==3.46.0 và đặt OPENAI_API_KEY trong môi trường.

# File: app/prompts/summarize.v1.md
Tóm tắt văn bản sau trong đúng 5 gạch đầu dòng.
Mỗi dòng tối đa 20 từ. Không thêm thông tin không có trong văn bản.

Văn bản:
{{document}}
# File: app/providers/openai_adapter.py
from openai import OpenAI


class OpenAIAdapter:
    def __init__(self, model: str) -> None:
        self.model = model
        self.client = OpenAI()  # đọc OPENAI_API_KEY từ env

    def complete(self, prompt: str) -> str:
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            temperature=0,
        )
        return response.choices[0].message.content or ""
# File: app/cli.py
from pathlib import Path
import sys

from app.providers.openai_adapter import OpenAIAdapter

PROMPT_PATH = Path("app/prompts/summarize.v1.md")


def main(path: str) -> None:
    template = PROMPT_PATH.read_text(encoding="utf-8")
    document = Path(path).read_text(encoding="utf-8")
    adapter = OpenAIAdapter(model="gpt-6.1-terra")
    print(adapter.complete(template.replace("{{document}}", document)))


if __name__ == "__main__":
    main(sys.argv[1])

Chạy bằng python -m app.cli notes.txt. Điểm quan trọng không phải đoạn code này mà là các đường dẫn: prompt nằm ngoài code, model nằm trong một biến cấu hình, và entry point không biết gì về provider ngoài interface.

Thêm một test giữ hợp đồng prompt. Nó không kiểm tra model, chỉ kiểm tra file không bị sửa vô tình:

# File: tests/test_prompt_contract.py
from pathlib import Path

PROMPT = Path("app/prompts/summarize.v1.md")


def test_prompt_keeps_placeholder_and_constraints():
    text = PROMPT.read_text(encoding="utf-8")
    assert "{{document}}" in text
    assert "5 gạch đầu dòng" in text


def test_prompt_version_is_in_filename():
    assert PROMPT.name == "summarize.v1.md"

Config và secret

Config nên là một dataclass có kiểu, đọc từ biến môi trường, fail ngay nếu thiếu trường bắt buộc. Điều này biến lỗi cấu hình thành lỗi khởi động, rẻ hơn nhiều so với lỗi giữa request.

# File: app/config.py
import os
from dataclasses import dataclass


@dataclass(frozen=True)
class Settings:
    model: str
    max_output_tokens: int
    tenant: str

    @classmethod
    def from_env(cls) -> "Settings":
        model = os.environ.get("AI_MODEL")
        if not model:
            raise RuntimeError("thiếu AI_MODEL")
        return cls(
            model=model,
            max_output_tokens=int(os.environ.get("AI_MAX_OUTPUT", "1024")),
            tenant=os.environ.get("AI_TENANT", "default"),
        )

Ba quy tắc secret: không commit .env; không đưa secret vào prompt, log hay trace; dùng credential ngắn hạn được inject ở runtime cho từng tool. Nếu agent hoặc pipeline đọc cả workspace, một file .env nằm trong đó là một sự cố đang chờ xảy ra.

Với nhiều môi trường, giữ cùng một schema và đổi nguồn giá trị: env cho local, secret manager cho staging và production. Đừng tạo ba file cấu hình có ba bộ khóa khác nhau; đó là cách sinh ra lỗi “staging chạy, production không”.

Pin phụ thuộc

Pin cả ba tầng, không chỉ tầng trên cùng:

  • Provider SDK — openai==3.46.0, anthropic==2.6.0, google-genai==3.0.0 tại thời điểm viết. SDK đổi cách serialize tool call và usage, nên pin là bắt buộc.
  • Framework — langchain==1.4.9, langgraph==1.2.20, llama-index-core==0.14.25. LlamaIndex còn ở 0.x, chênh một minor có thể đổi import.
  • Công cụ eval — deepeval==4.3.3, ragas==0.4.3, promptfoo@0.125.1. Metric đổi theo bản, nên điểm số cũ không so sánh được với bản mới.

Dùng lockfile và cài bằng lockfile trong CI. pip install -r requirements.txt không pin transitive dependency sẽ cho bạn một môi trường khác mỗi lần build.

Ba loại migration

Prompt. Không sửa summarize.v1.md. Tạo summarize.v2.md, chạy eval trên cùng dataset, so sánh với baseline, rồi rollout theo tỉ lệ. Nếu kết quả tệ hơn, xóa v2; v1 vẫn còn nguyên. Đây là lợi ích lớn nhất của prompt-as-file.

Model. Đổi model là đổi cả hành vi lẫn giá. Chạy eval, đo chi phí mỗi task, và chạy shadow traffic trên 5–10% request trước khi chuyển toàn bộ. Giữ một đường fallback có cấu hình, nhưng nhớ rằng fallback đổi tool schema và cách tính token; phải test chính đường fallback đó.

Index. Không ghi đè collection đang phục vụ. Tạo collection mới, build xong, kiểm tra số node và spot-check truy vấn, rồi chuyển alias. Giữ collection cũ vài ngày để rollback. Với pgvector hay Qdrant, alias là cách rẻ nhất để đổi mà không sửa code.

CI eval và observability

CI nên có ba tầng, chạy ở ba tần suất khác nhau:

  • Mỗi commit — lint, type check, unit test, contract test. Không gọi API thật; dùng fixture đã ghi.
  • Mỗi PR chạm prompt hoặc provider — eval trên dataset nhỏ (20–30 mẫu), so với baseline, fail nếu metric giảm quá ngưỡng bạn đặt.
  • Hằng đêm — eval đầy đủ, đo chi phí, kiểm tra drift của dữ liệu đầu vào.

Đừng đặt ngưỡng tuyệt đối cho điểm LLM-as-judge. Judge có position bias, verbosity bias và self-preference; điểm không calibrated. Hãy so sánh tương đối với baseline và dùng judge khác họ model khi có thể.

Observability không phải log mọi thứ. Cần bốn thứ: trace ID xuyên suốt request, span cho retrieval/model/tool, token accounting tách input — cached — output — reasoning, và p95 latency. Reasoning token tính như output, nên đừng gộp vào input. OTel GenAI đang ở mức Development, nên pin semantic conventions và chấp nhận phải đổi tên attribute.

Chi phí nên được gắn nhãn theo tenant và feature ngay từ span đầu tiên. Nếu không, khi hóa đơn tăng bạn chỉ biết “tăng”, không biết ai tăng.

Monorepo hay service?

Tình huống Chọn Lý do
Một sản phẩm, prompt và eval dùng chung Monorepo Đổi prompt và chạy eval trong cùng PR
Nhiều team, chu kỳ release khác nhau Monorepo có package Chia package nhưng giữ một CI và một chuẩn eval
Dịch vụ scale độc lập, ranh giới rõ Service riêng Deploy và rollback độc lập
Yêu cầu cô lập dữ liệu hoặc tuân thủ Service riêng Ranh giới quyền và dữ liệu rõ ràng hơn

Đừng tách service trước khi có nhu cầu thật. Mỗi service là một pipeline deploy, một bộ credential và một nơi để eval bị bỏ quên. Monorepo với package rõ ràng thường đi được xa hơn bạn nghĩ.

Pitfall

  • Prompt trong code. Sửa một chữ, không ai biết, không có diff để review. Chuyển ra file trước khi có người thứ hai.
  • Model ID rải rác. Một chỗ đổi, mười chỗ quên. Đưa vào config và kiểm tra bằng test.
  • Eval trong notebook. Không chạy trong CI, không ai review, và biến mất khi máy đổi. Đưa dataset vào repo dạng JSONL.
  • Secret trong file config. Kể cả file “chỉ dùng local”. Một lần commit là phải rotate.
  • Trace không lấy mẫu. Trace toàn bộ làm chi phí lưu trữ tăng và làm tăng nguy cơ lộ dữ liệu. Lấy mẫu và redact trước khi ghi.
  • Đổi index không có alias. Rollback nghĩa là build lại từ đầu, đúng lúc bạn đang cần rollback nhanh nhất.

Nhìn trước 2027

Model sẽ tiếp tục đổi, và giá sẽ tiếp tục đổi. Cấu trúc tốt không giảm số lần đổi; nó giảm thời gian mỗi lần đổi. Hướng đi rõ là eval-as-code và prompt-as-artifact trở thành mặc định, còn tracing sẽ dần ổn định khi OTel GenAI ra khỏi trạng thái Development. Đầu tư hôm nay vào ba thứ đó sinh lãi lâu hơn đầu tư vào một framework cụ thể.

Checklist

  • Tạo prompts/ với file có version và registry ghi hash, owner.
  • Đưa dataset eval vào repo; chạy trong CI ở chế độ so sánh baseline.
  • Gom mọi lời gọi model vào providers/; model ID chỉ xuất hiện trong config.
  • Pin provider SDK, framework và công cụ eval; cài bằng lockfile.
  • Gắn nhãn chi phí theo tenant và feature ngay từ span đầu tiên.
  • Viết quy trình migration cho prompt, model và index trước khi cần dùng.

Bài liên quan