Deploy AI agent: những thứ cần có trước khi cho khách thật dùng
Deploy AI agent: bọc agent thành dịch vụ HTTP có kiểm tra sức khỏe, giới hạn tần suất, số đo, công tắc tắt và dừng êm, thử trên máy bằng tải giả lập.
Trước khi deploy AI agent cho khách thật, bạn cần năm thứ ngoài chính agent: kiểm tra sức khỏe, giới hạn đầu vào, số đo, công tắc tắt agent và cách dừng êm. Bài này xây năm thứ đó và thử trên máy, chưa deploy lên máy chủ nào. Bạn đã sẵn sàng cho khách thật chưa?
Agent chạy trên máy mình, vậy còn thiếu gì?
Ở tập trước của Xây AI agent đầu tiên, agent của quán Mộc đã biết chuyển những tin nhạy cảm cho người thật và ghi nhật ký từng bước. (Quán Mộc là nhân vật minh họa của series này.) Nhưng nó vẫn là một thư viện mà chỉ chính mình gọi. Khách thật thì không chạy node trên máy của họ; họ gửi tin qua mạng, vào bất cứ lúc nào, và có người gửi một tin dài mười nghìn chữ hay bấm gửi hai trăm lần.
Mình cần nói rõ một điều trước khi đi tiếp: mình không đưa nó lên máy chủ nào trong bài này. Mọi thứ dưới đây chạy trên máy của mình bằng Node 22 trên Windows, với mô hình giả. Mục đích là xây và thử các thứ mà một lần deploy thật sẽ cần, để khi bạn deploy lên nền tảng nào cũng đã có chúng. Phần chưa thử mình sẽ nói ở cuối.
Thư mục src/ của dịch vụ có sáu file là tổng đài của tập trước (trong đó có tong-dai.ts, quyet-dinh.ts, nhat-ky.ts), gần như giữ nguyên. Mình chỉ thêm một lý do chuyển mới là agent-tat và một hàm chuyenThang (chuyển thẳng cho người, không qua mô hình). Ba file mới là cau-hinh.ts (đọc biến môi trường), so-do.ts (bộ đếm) và may-chu.ts (máy chủ HTTP). Bài này tập trung vào may-chu.ts, vì nó là nơi mọi thứ gặp nhau.
Cấu hình lấy từ môi trường, và sai thì không khởi động
Mình lấy lại bài học ở series Kỹ năng về biến môi trường: đọc process.env một lần, kiểm tra, đổi kiểu, và nếu sai thì dừng ngay lúc khởi động, liệt kê hết mọi chỗ sai. docCauHinh trong cau-hinh.ts làm đúng việc đó, nhưng viết thẳng không dùng thư viện. Dịch vụ có sáu giá trị: PORT, AGENT_TAT (công tắc), GIOI_HAN_MOI_PHUT, MAX_DO_DAI_TIN, DO_TRE_MO_HINH_MS (giả lập độ trễ của mô hình, mặc định 0) và ADMIN_KEY (bắt buộc, ít nhất 16 ký tự, dùng để xem số đo).
Chạy thiếu khóa quản trị thì dịch vụ không mở cổng:
Cấu hình sai, dịch vụ không khởi động:
- ADMIN_KEY: bắt buộc, dài ít nhất 16 ký tựMình không dán cau-hinh.ts vào đây (khoảng 60 dòng, cùng ý với bài biến môi trường). Điều đáng nhớ là thông báo lỗi nhắc giá trị sai của PORT hay AGENT_TAT nhưng không bao giờ in khóa, và test kiểm điều đó.
Kiểm tra sức khỏe: sống và sẵn sàng là hai chuyện khác nhau
Nền tảng chạy dịch vụ của bạn cần hỏi được "bạn còn sống không" và "bạn nhận việc được chưa". Mình làm hai đường: GET /healthz trả {"ok":true} miễn là tiến trình còn chạy, và GET /readyz trả 200 khi dịch vụ sẵn sàng nhận tin, 503 khi đang dừng. Hai thứ này tách nhau vì khi dịch vụ đang dừng, nó vẫn sống (đang xử lý nốt việc dở) nhưng không nên nhận việc mới.
Hai đường này không đòi khóa, vì chúng không trả thông tin gì ngoài trạng thái.
Giới hạn đầu vào: không tin ai gửi gì
Đường nhận tin là POST /tin, thân là JSON có maHoiThoai và tin. Hàm xuLyTin kiểm theo thứ tự rẻ trước, đắt sau. Mình hỏi nó làm gì trước khi dán: nó nhận một yêu cầu, trả về mã HTTP và nội dung JSON, và chỉ gọi tổng đài khi mọi kiểm tra đều qua.
async function xuLyTin(req: IncomingMessage, res: ServerResponse): Promise<void> {
if (dangDung) return gui(res, 503, { loi: "dang-dung" });
const than = await docThan(req); // đọc tối đa 10.000 byte, quá thì trả null
if (than === null) return gui(res, 413, { loi: "than-qua-lon" });
let dauVao: { maHoiThoai?: unknown; tin?: unknown };
try {
dauVao = JSON.parse(than);
} catch {
return gui(res, 400, { loi: "json-sai" });
}
const { maHoiThoai, tin } = dauVao;
if (typeof maHoiThoai !== "string" || !/^[\w-]{1,64}$/.test(maHoiThoai)) return gui(res, 400, { loi: "ma-hoi-thoai-sai" });
if (typeof tin !== "string" || tin.trim() === "") return gui(res, 400, { loi: "tin-rong" });
if (tin.length > cauHinh.MAX_DO_DAI_TIN) return gui(res, 413, { loi: "tin-qua-dai", toiDa: cauHinh.MAX_DO_DAI_TIN });
if (quaGioiHan(maHoiThoai)) return gui(res, 429, { loi: "qua-nhieu-tin", thuLaiSau: "60s" });
// ... đếm tinNhan, đợi DO_TRE_MO_HINH_MS để giả lập mô hình ...
const traLoi = cauHinh.AGENT_TAT ? tongDai.chuyenThang(maHoiThoai, tin) : tongDai.khach(maHoiThoai, tin);
// ... đếm daTraLoi / daChuyen / daImLang và ghi độ trễ ...
gui(res, 200, { traLoi });
}Mỗi giới hạn có lý do riêng, và đều là chuyện tiền hoặc an toàn. Kích thước thân và độ dài tin giới hạn vì tin càng dài thì mô hình càng tốn token (nhắc lại bài về chi phí), và vì một thân yêu cầu lớn tùy ý là cách dễ nhất để làm cạn bộ nhớ của dịch vụ. maHoiThoai chỉ nhận chữ, số, gạch dưới và gạch nối, tối đa 64 ký tự, vì nó đi vào nhật ký và vào khóa của bộ nhớ, nên không nên cho ai nhét gì vào đó. Giới hạn tần suất (quaGioiHan) đếm số tin của mỗi cuộc trò chuyện trong 60 giây gần nhất, và mặc định là 20. Một vòng lặp lỗi phía khách, hay một người cố tình, có thể làm hàng nghìn cuộc gọi mô hình trong một phút.
Mình thử giới hạn tần suất bằng node thu-tai.ts (phần thứ hai): một khách gửi dồn 25 tin liên tiếp.
--- 2. Một khách gửi dồn 25 tin liên tiếp (giới hạn 20 tin mỗi phút)
Mã trả về: 20 lần 200, 5 lần 429
tuChoiGioiHan trong số đo: 520 tin đầu qua, 5 tin sau nhận 429 (quá nhiều yêu cầu), và con số 5 cũng hiện trong số đo. Test còn kiểm hai điều khác: sau 61 giây thì khách đó gửi lại được, và một khách khác không bị ảnh hưởng.
Một điều về giới hạn này mình phải nói thẳng: nó nằm trong bộ nhớ của một tiến trình. Nếu bạn chạy hai bản của dịch vụ sau một bộ cân bằng tải, mỗi bản đếm riêng và giới hạn thực tế gấp đôi. Với dịch vụ nhiều bản, bạn cần một nơi đếm chung (ví dụ cơ sở dữ liệu hay một kho khóa-giá trị), điều mình chưa làm.
Số đo: thấy chuyện gì đang xảy ra
Khi dịch vụ chạy mà không ai nhìn, bạn chỉ biết có chuyện khi khách phàn nàn. so-do.ts giữ vài bộ đếm trong bộ nhớ và đo độ trễ của mỗi yêu cầu: số tin nhận, số tin agent trả lời, số cuộc trò chuyện được chuyển (và theo lý do nào), số tin bị từ chối vì giới hạn hoặc độ dài, số lỗi nội bộ, và độ trễ p50, p95 và lớn nhất. Đường GET /metrics trả chúng ra, nhưng bắt buộc có header x-admin-key đúng khóa quản trị (so bằng timingSafeEqual), vì các con số này không dành cho khách.
Để có số liệu có ý nghĩa mình viết phần đầu của thu-tai.ts: 300 tin từ 100 khách, 10 yêu cầu cùng lúc, mô hình giả chậm 50 ms, và cứ 10 tin thì có một tin thuộc loại cần chuyển cho người.
--- 1. Tải đều: 300 tin, 100 khách, 10 yêu cầu cùng lúc, mô hình giả chậm 50 ms (cứ 10 tin có 1 tin cần chuyển cho người)
Xong sau 1929 ms. Mã trả về: {"200":300}
Số đo: {"agentTat":false,"tinNhan":300,"daTraLoi":270,"daImLang":20,"daChuyen":10,"chuyenTheoLyDo":{"khach-yeu-cau":2,"hoan-tien":3,"di-ung":1,"khieu-nai":3,"agent-khong-chac":1},"tuChoiGioiHan":0,"tuChoiDoDai":0,"loiNoiBo":0,"doTreMs":{"p50":58,"p95":60,"toiDa":69}}Cả 300 tin trả 200. Độ trễ p50 là 58 ms và p95 là 60 ms, tức khoảng 50 ms của mô hình giả cộng vài mili giây xử lý; mình nhấn mạnh rằng đây là con số của một máy, một tiến trình và một mô hình giả, nên nó không nói gì về độ trễ khi gọi một mô hình thật.
Bạn thấy daTraLoi là 270, daImLang là 20 và daChuyen là 10. Ba con số này cộng lại bằng 300, nhưng lần chạy đầu của mình không như thế, và đó là chỗ mình học được nhiều nhất trong bài này. Lần đầu mình chỉ có hai bộ đếm là daTraLoi và daChuyen, và số daTraLoi cao tới mức làm mình yên tâm. Nhưng một cuộc trò chuyện đã được chuyển cho người thì mỗi tin sau của khách chỉ nhận câu "Mộc đã chuyển cho nhân viên rồi" mà không qua mô hình. Bộ đếm cũ cộng những tin đó vào "agent đã trả lời". Một con số trông khỏe nhưng nói sai về những gì agent thực sự làm. Mình thêm bộ đếm thứ ba, daImLang, cho đúng trường hợp này.
Cũng lần chạy đầu đó, số cuộc chuyển lên tới 30 trong 300 tin, trong đó 27 là lý do lap-lai (khách hỏi lại y nguyên). Lỗi không phải ở dịch vụ mà ở dữ liệu thử của mình: mình cho mỗi khách gửi đi gửi lại đúng một câu, và quy tắc của tập trước làm đúng việc nó được viết để làm. Mình sửa dữ liệu thử cho mỗi khách gửi các câu khác nhau. Tuy nhiên bài học vẫn đáng giữ: một bộ thử tải ngây thơ có thể kích hoạt đúng những quy tắc bạn muốn kiểm, và kết quả sẽ trông như một lỗi của dịch vụ.
Công tắc tắt agent
Có một thứ mình thấy nên có trước cả khi nghĩ tới mô hình tốt hơn: khả năng tắt agent ngay mà không phải deploy lại. Nếu mô hình bắt đầu trả lời sai hàng loạt, hoặc hóa đơn tăng bất thường, bạn cần một cách dừng trong vài giây. Mình làm nó bằng biến AGENT_TAT. Khi nó là true, hàm chuyenThang bỏ qua mô hình, tạo phiếu với lý do agent-tat và nói với khách một câu trung thực rằng hôm nay nhân viên trả lời trực tiếp. Phần thứ ba của thu-tai.ts thử nó:
--- 3. Công tắc tắt agent (AGENT_TAT=true)
Khách: quán mấy giờ mở cửa?
→ 200 Hôm nay Mộc nhờ nhân viên trả lời trực tiếp. Nhân viên sẽ trả lời bạn trong giờ mở cửa.
Khách: đơn 1042 đâu rồi
→ 200 Mộc đã chuyển cho nhân viên rồi, nhân viên sẽ đọc tin của bạn.
Số đo: agentTat=true, daTraLoi=0, daImLang=1, daChuyen=1, {"agent-tat":1}Hãy nhìn agentTat=true và {"agent-tat":1} trong số đo, và daTraLoi=0: agent không trả lời tin nào. Test còn kiểm rằng nhật ký của cuộc trò chuyện đó không có sự kiện quyet-dinh hay agent-tra-loi nào, tức là mô hình thật sự không được gọi.
Đây là công tắc cơ bản nhất, và nó có giới hạn rõ ràng. AGENT_TAT là biến môi trường, nghĩa là trên hầu hết nền tảng, đổi nó vẫn đòi khởi động lại dịch vụ (nhanh hơn deploy, nhưng không phải tức thì). Một công tắc thật sự tức thì cần đọc cờ từ một nơi thay đổi được khi đang chạy, ví dụ một dòng trong cơ sở dữ liệu, và mình chưa làm. Một số bài viết về agent trong production cũng khuyên thử công tắc theo lịch để không phát hiện ra nó hỏng giữa lúc có sự cố, và theo mình lời khuyên đó có lý.
Dừng êm: đừng cắt ngang người đang nói
Khi bạn deploy bản mới, nền tảng sẽ dừng bản cũ. Nếu dừng bằng cách giết ngay, những khách đang chờ câu trả lời thấy kết nối bị đứt. Dừng êm nghĩa là ngừng nhận việc mới và đợi việc đang làm xong. Hàm dung trong may-chu.ts làm hai bước: đánh dấu "chưa sẵn sàng" (để /readyz trả 503) và đợi một khoảng cho bộ cân bằng tải biết mà ngừng gửi việc tới, rồi ngừng nhận kết nối mới và đợi các yêu cầu đang chạy xong.
const dung = async (docChoMs = 0) => {
dangDung = true;
if (docChoMs > 0) await chờ(docChoMs);
await new Promise<void>((xong, hong) => {
const vong = setInterval(() => server.closeIdleConnections(), 50);
server.close((loi) => {
clearInterval(vong);
loi ? hong(loi) : xong();
});
});
};Đoạn này có hai chỗ mình viết sai ở lần đầu. Bản đầu của dung chỉ gọi server.close() rồi server.closeIdleConnections() một lần. Tài liệu Node.js về `server.close` nói nó ngừng nhận kết nối mới và gọi callback khi mọi kết nối đã đóng. Mình thử với một yêu cầu đang chạy (mô hình giả chậm 400 ms) và đo thời gian dừng:
/readyz lúc đang dừng: kết nối bị từ chối
Yêu cầu đang xử lý lúc dừng: trả về 200
Dịch vụ dừng hẳn sau 3310 ms kể từ lệnh dừng (chờ yêu cầu đó xong)Có hai điều sai. Một, yêu cầu đang xử lý trả 200 đúng như mong muốn, nhưng dịch vụ dừng hẳn sau 3,3 giây, trong khi yêu cầu đó chỉ cần khoảng 0,3 giây. Lý do: sau khi trả lời, kết nối của khách vẫn mở (keep-alive) để dùng lại, và server.close đợi kết nối đó đóng. Lúc mình gọi closeIdleConnections thì kết nối chưa rảnh (nó đang xử lý) nên không bị đóng, và sau đó không ai đóng nó. Hai, /readyz không bao giờ trả được 503 vì server.close từ chối kết nối mới ngay lập tức, nên bộ cân bằng tải chỉ thấy "kết nối bị từ chối" chứ không phải một câu trả lời "chưa sẵn sàng".
Mình sửa hai chỗ như trong đoạn code ở trên: thêm thời gian chờ docChoMs trước khi đóng (trong lúc chờ /readyz trả 503 và dịch vụ vẫn xử lý việc dở), và gọi closeIdleConnections liên tục mỗi 50 ms cho tới khi đóng xong. Chạy lại, với thời gian chờ 200 ms:
/readyz lúc đang dừng: 503
Yêu cầu đang xử lý lúc dừng: trả về 200
Dịch vụ dừng hẳn sau 333 ms kể từ lệnh dừng (chờ yêu cầu đó xong)
Yêu cầu mới sau khi dừng: lỗi kết nối (ECONNREFUSED)Giờ /readyz trả 503 trong lúc chờ, yêu cầu dở vẫn được trả lời, dịch vụ dừng sau 333 ms (200 ms chờ cộng thời gian xong nốt việc), và sau đó kết nối mới bị từ chối.
Giới hạn thật của phần này: file chay.ts đăng ký dung() cho tín hiệu SIGTERM và SIGINT, nhưng trên Windows một SIGTERM từ bên ngoài giết tiến trình ngay lập tức, nên mình không thử được đường đó. Mình chỉ thử gọi hàm dung() trực tiếp, và thử Ctrl+C thì chưa. Trên Linux (nơi hầu hết dịch vụ chạy thật) hành vi này sẽ khác, và bạn nên tự thử.
Khi có lỗi bất ngờ, khách không nên thấy stack trace
Một chỗ cuối cùng: nếu bên trong dịch vụ có gì đó ném lỗi, createServer bắt nó, tăng bộ đếm loiNoiBo, ghi sự kiện vào nhật ký (kèm thông báo lỗi, để bạn tìm được), và chỉ trả cho khách {"loi":"loi-noi-bo"} với mã 500. Test của mình làm cho tổng đài ném lỗi "mô hình sập", rồi kiểm ba điều: khách nhận đúng chuỗi đó, bộ đếm là 1, và nhật ký có dòng nhắc tới "mô hình sập". Stack trace chứa đường dẫn file và tên thư viện, thứ không có lý do gì để lộ ra ngoài.
Một bài học nhỏ khi thử bằng curl
Khi chạy dịch vụ thật bằng npm start rồi thử bằng curl -d '{"maHoiThoai":"c-1","tin":"quán có món gì?"}' trong Git Bash trên Windows, agent không trả lời thực đơn mà chuyển cuộc trò chuyện cho người, với lý do agent-khong-chac. Mình tưởng quy tắc hỏng. Hóa ra tiếng Việt có dấu trong tham số dòng lệnh bị lỗi mã hóa trước khi tới dịch vụ, nên mô hình giả không nhận ra câu hỏi. Khi mình để JSON trong một file UTF-8 và gửi bằng curl --data-binary @tin.json, nó trả đúng danh sách món. Dịch vụ không sai, nhưng điều này cho thấy một phép thử thủ công có thể đánh lừa bạn rằng hệ thống hỏng (hay chạy tốt) vì lý do không liên quan, và vì vậy mình ưu tiên test tự động hơn thử tay.
Giữ các điều này bằng test
Mười lăm test của tập này chạy máy chủ thật trên cổng ngẫu nhiên và gọi nó bằng fetch. Chúng kiểm: cấu hình mặc định, biến rỗng coi như chưa đặt, báo hết ba lỗi cùng lúc mà không in khóa, thiếu ADMIN_KEY thì không khởi động, phân vị của 100 số đo, /healthz và /readyz, /metrics cần đúng khóa, các đầu vào sai bị từ chối đúng mã (JSON hỏng, mã cuộc trò chuyện sai, tin rỗng), tin quá dài và thân quá lớn bị 413 và được đếm, giới hạn tần suất (tin thứ 21, sau 61 giây, và khách khác), việc tin đi qua tổng đài và được đếm đúng, công tắc tắt, lỗi bất ngờ trả 500 gọn, dừng êm chờ yêu cầu đang chạy, và /readyz trả 503 trong thời gian chờ. Bạn chạy bằng npm test (file test nằm trong repo demo, bài này mình không dán).
# tests 15
# pass 15
# fail 0Những điều bài này chưa làm
Mình nói thẳng giới hạn, vì "production" là chữ dễ bị dùng quá tay. Một, mình chưa deploy lên đâu cả, nên không có số liệu từ môi trường thật, không có Dockerfile đã được thử, và không có thử với bộ cân bằng tải. Hai, không có mô hình thật nào được gọi; độ trễ 50 ms là con số mình đặt. Ba, số đo nằm trong bộ nhớ, mất khi khởi động lại, và mình không có cảnh báo: không ai bị báo khi loiNoiBo tăng. Bốn, giới hạn tần suất không dùng được khi có nhiều bản dịch vụ. Năm, ADMIN_KEY là một khóa tĩnh, nên nếu nó lộ thì ai cũng xem được số đo; dịch vụ thật nên có cách xoay khóa. Sáu, dữ liệu cuộc trò chuyện và phiếu nằm trong bộ nhớ nên mất khi khởi động lại. Với khách thật đó là vấn đề lớn nhất trong cả danh sách này, vì một phiếu chuyển cho nhân viên biến mất khi dịch vụ restart là đúng điều tập trước cố tránh.
Agent đã có thể ra mắt, nhưng nó mới chỉ phục vụ khách
Sau mười bốn bài, agent của quán Mộc đi từ một lệnh gọi mô hình tới một dịch vụ biết trả lời, tra đơn, chuyển cho người, nhớ chi phí, đo độ trễ và tắt được khi cần. Nhưng tất cả những thứ đó phục vụ khách ngoài quán. Bên trong quán còn một nhóm người khác cũng cần một trợ lý: nhân viên pha chế, người đóng gói đơn, chủ quán xem doanh thu. Những câu họ hỏi khác (tồn kho, ca làm, báo cáo), dữ liệu họ được xem cũng khác, và rủi ro cũng khác: một agent cho nội bộ đọc được những thứ mà khách không được thấy. Làm một agent cho nội bộ quán là việc của các bài viết sau.
Bạn theo dõi cả hành trình ở Xây AI agent đầu tiên. Nếu muốn nhớ lại vì sao tin có thể tốn tiền như vậy, hãy đọc chi phí AI agent. Các câu hỏi về AI agent nằm trong ngân hàng câu hỏi phỏng vấn.