Chạy OpenWiki trong thực tế: Tại sao mô hình bạn chọn lại quyết định mọi thứ

Phần 2/3 – Một lần chạy tạo tài liệu thực tế, mô hình không thể hoàn thành, mô hình có thể hoàn thành và chi phí thực tế của tài liệu chất lượng. Trong Phần 1, chúng tôi đã đề cập đến OpenWiki – cách tiếp cận của LangChain đối với ý tưởng "LLM Wiki" của Karpathy, được áp dụng cho các cơ sở mã – và việc cài đặt nó dễ dàng đến mức nào. Phần này là một kiểm chứng thực tế: điều gì đã xảy ra khi tôi hướng nó vào một dự án thực tế và bài học bất ngờ nhất. Tóm tắt: với một công cụ tài liệu dựa trên tác nhân (agentic doc tool), việc lựa chọn mô hình không phải là một nút điều chỉnh – đó là sự khác biệt giữa một wiki hoàn chỉnh và một lần chạy bị lỗi. Thiết lập Tôi đã hướng OpenWiki vào một monorepo thực tế – một backend Spring Boot 3.1 / Java 17 với frontend Angular 20. Vài trăm tệp nguồn, một mô hình miền (domain model) thực sự, các quy tắc nghiệp vụ thực tế. Chính xác là loại cơ sở mã mà tài liệu tốt mang lại lợi ích và nơi "chỉ đọc mã" không thể mở rộng cho người mới. Tôi đã cấu hình nó với Anthropic và cung cấp một lời nhắc khởi tạo (seed prompt) phong phú mô tả hình dạng và miền của kho lưu trữ, sau đó để nó chạy ở chế độ một lần (--print) để nó khám phá và viết mà không cần tôi giám sát một vòng lặp trò chuyện. Lần chạy không thể hoàn thành Lựa chọn đầu tiên của tôi là Claude Sonnet – mặc định hợp lý cho một công việc "chất lượng nhưng không cao cấp". Nó kết nối tốt, bắt đầu khám phá cơ sở mã... và sau đó lần chạy bị lỗi. Không phải do lỗi mạng hay thông báo hết token. Nó bị lỗi do một lệnh gọi công cụ (tool call) không đúng định dạng: tác nhân đã phát ra một lệnh gọi công cụ thiếu một trường bắt buộc, framework cơ bản đã từ chối nó dựa trên lược đồ của nó, và – vì đây là một lần chạy không có giao diện người dùng, không tương tác – toàn bộ quá trình đã bị lỗi thay vì phục hồi. Tôi đã chạy lại. Nó lại bị lỗi, ở một điểm khác, trên một công cụ khác. Một lần là lệnh gọi ghi tệp thiếu đối số; một lần là lệnh gọi danh sách việc cần làm với các mục thiếu một trường bắt buộc. Mẫu hình này đã cho thấy: đây không phải là một lỗi không may. Sonnet đã liên tục tạo ra các lệnh gọi công cụ không tuân thủ các lược đồ nghiêm ngặt mà framework tác nhân yêu cầu, và lần chạy không có giao diện người dùng không có cách nào để phục hồi từ đó. Điều này đáng để suy nghĩ, bởi vì nó phản trực giác. Sonnet là một mô hình mạnh mẽ. Nó viết văn xuôi xuất sắc. Nhưng OpenWiki không phải là một tác vụ "viết cho tôi một đoạn văn" – về cơ bản, nó là một vòng lặp gọi công cụ dựa trên tác nhân đòi hỏi khắt khe: hàng chục đến hàng trăm lượt, mỗi lượt phát ra các lệnh gọi công cụ có cấu trúc để đọc tệp, tìm kiếm và viết trang, đôi khi phân nhánh thành các tác nhân phụ. Trong bối cảnh đó, điều quan trọng nhất không phải là sự hùng biện – mà là sự tuân thủ không ngừng, chính xác các lược đồ công cụ, hết lượt này đến lượt khác. Một mô hình chỉ cần trượt chân đôi khi cũng sẽ trượt chân ở lệnh gọi khiến lần chạy bị lỗi. Việc điều chỉnh lời nhắc (prompt-nudging) cũng không cứu được. Tôi đã thêm các hướng dẫn rõ ràng về việc sử dụng công cụ; sau đó nó lại gặp lỗi ở một công cụ mà tôi thậm chí còn chưa đề cập. Bạn không thể thoát khỏi vấn đề độ tin cậy của mô hình bằng cách điều chỉnh lời nhắc. Lần chạy thành công Vì vậy, tôi đã chuyển mô hình sang Claude Opus 4.8 (ID mô hình claude-opus-4-8) và không thay đổi bất cứ điều gì khác về tác vụ. Nó chạy trơn tru. Nó đã khám phá kho lưu trữ, điều động các tác nhân phụ nghiên cứu trên các miền chính, lập kế hoạch và viết toàn bộ bộ tài liệu – tổng quan kiến trúc, luồng xác thực, mô hình miền, giao diện API REST, hướng dẫn frontend và trang vận hành/sổ tay hướng dẫn – tất cả đều được liên kết chéo, tất cả đều dựa trên mã nguồn hiện tại. Nó thậm chí còn gắn cờ rằng một tài liệu cũ hơn đã có trong kho lưu trữ đã lỗi thời so với mã, và kiên quyết từ chối tái tạo một số thông tin xác thực mà nó tìm thấy trong tệp cấu hình. Chín trang, mạch lạc và chính xác, trong lần thử hoàn thành đầu tiên. Biến số duy nhất được thay đổi là mô hình. Việc Opus tuân thủ chặt chẽ hơn các lệnh gọi công cụ có cấu trúc đã tạo nên toàn bộ sự khác biệt giữa việc "sập giữa chừng" và "hoàn thành". (Để đầy đủ: cũng có một vài lỗi nhỏ ở phiên bản đầu liên quan đến cách công cụ đọc một số loại tệp nhất định – những lỗi thường thấy ở bản phát hành v0.x – và đang được khắc phục. Nhưng đó chỉ là những vấn đề nhỏ. Vấn đề về độ tin cậy của mô hình mới là câu chuyện thực sự.) Bài học rút ra Nếu có một điều cần ghi nhớ từ đây: đối với OpenWiki – và các công cụ tài liệu dựa trên tác nhân nói chung – hãy ưu tiên chọn mô hình dựa trên độ tin cậy của lệnh gọi công cụ trước, sau đó mới đến chất lượng văn phong. Lỗi không phải là "tài liệu kém chất lượng một chút". Mà là "quá trình chạy không bao giờ kết thúc". Một mô hình rẻ hơn hoặc nhẹ hơn có thể là một sự tiết kiệm sai lầm nếu nó không thể hoàn thành vòng lặp. Chi phí thực sự của tài liệu chất lượng Đây là phần không ai đưa vào README. Một lần chạy OpenWiki tốt không phải là một lệnh gọi API duy nhất – đó là một phiên làm việc dài của tác nhân, đọc phần lớn kho lưu trữ của bạn, suy luận về nó, tạo ra các tác nhân phụ và viết nhiều trang. Đó là rất nhiều lệnh gọi mô hình, và chi phí token là đáng kể. Giá của Anthropic có liên quan [1] (mỗi 1 triệu token, tại thời điểm viết bài): Một vài nhận xét chân thực về chi phí: Mô hình có khả năng hoàn thành công việc sẽ rẻ hơn mô hình rẻ tiền nhưng không hoàn thành. Ba lần chạy Sonnet bị lỗi vẫn tiêu tốn token – chúng đã khám phá kho lưu trữ trước khi dừng. Một lần chạy Opus sạch sẽ tạo ra sản phẩm có giá trị hơn nhiều so với một đống sản phẩm dở dang rẻ tiền hơn. Hãy tính tỷ lệ hoàn thành vào chi phí, không chỉ là giá mỗi token. Chi phí tăng theo kích thước và độ sâu của kho lưu trữ. Càng nhiều tệp cần đọc, càng nhiều nghiên cứu của tác nhân phụ, càng nhiều trang cần viết – càng nhiều token. Một thư viện nhỏ chỉ tốn vài xu; một monorepo lớn được tài liệu hóa kỹ lưỡng là một khoản chi đáng kể (mặc dù không quá xa xỉ). Hướng nó vào mã nguồn, không phải các tạo phẩm. Trước khi chạy, hãy đảm bảo OpenWiki đang xem xét mã, không phải các tệp lộn xộn. Đầu ra bản dựng (target/, dist/, build/), node_modules/, lockfiles, mã được tạo và các tài sản nhị phân lớn làm tăng token và nhiễu mà không thêm bất cứ điều gì mà người đọc muốn tài liệu hóa. Hầu hết những thứ này đã có trong .gitignore của bạn và OpenWiki tôn trọng điều đó – nhưng đáng để xem xét trước một lệnh --init lớn, vì một cây thư mục gọn gàng hơn có nghĩa là một lần chạy rẻ hơn và một wiki chặt chẽ hơn tài liệu hóa hệ thống của bạn thay vì những gì còn sót lại của trình biên dịch. Bảo trì rẻ hơn nhiều so với tạo mới. Lệnh --init ban đầu đọc mọi thứ. Các lần chạy --update tiếp theo chỉ xem xét những gì đã thay đổi kể từ lần commit cuối cùng, vì vậy việc duy trì liên tục