Markdown có thể chạy: Cách mạng hóa kiểm thử tài liệu với Hugging Face

Tài liệu đóng vai trò là cầu nối quan trọng giữa các nhà phát triển và công cụ của họ, nhưng độ tin cậy của nó thường bị suy yếu bởi một vấn đề phổ biến: lệch tài liệu. Khi phần mềm phát triển, các ví dụ mã trong tài liệu có thể âm thầm bị hỏng, dẫn đến sự thất vọng, lãng phí thời gian và làm xói mòn lòng tin. Hugging Face, một công ty dẫn đầu trong đổi mới AI, đang giải quyết thách thức này trực tiếp với dự án doc-builder của mình, giới thiệu các khối Markdown có thể chạy đảm bảo rằng các ví dụ tài liệu không chỉ mang tính minh họa mà còn được kiểm thử nghiêm ngặt. Cách tiếp cận hiện đại này định nghĩa lại cách chúng ta tiếp cận tài liệu có thể thực thi, kết hợp sự rõ ràng của tài liệu tốt với sự mạnh mẽ của kiểm thử liên tục.

Thách thức: Kết nối Tài liệu và Tính toàn vẹn Mã

Triết lý cốt lõi đằng sau tài liệu có thể chạy không phải là mới. Trong nhiều thập kỷ, cộng đồng Python đã ủng hộ các ví dụ trong tài liệu mà người dùng có thể sao chép, dán và mong đợi chạy trơn tru. Tuy nhiên, việc duy trì lý tưởng này trên các dự án lớn, phát triển nhanh chóng như thư viện Transformers của Hugging Face là một nhiệm vụ khổng lồ. Xác minh thủ công là không thực tế, và các phương pháp truyền thống thường buộc phải đánh đổi giữa tài liệu rõ ràng và kiểm thử hiệu quả.

Vấn đề phát sinh từ sự khác biệt cơ bản trong các yêu cầu:

Các ví dụ tài liệu ưu tiên sự ngắn gọn, dễ đọc và tập trung vào việc giảng dạy. Chúng nhằm mục đích không có 'nhiễu'.
Các bài kiểm thử yêu cầu các xác nhận, thiết lập/gỡ bỏ, fixture, mocking và khả năng gỡ lỗi. Chúng ưu tiên sự mạnh mẽ và độ bao phủ.

Khi hai mối quan tâm này bị buộc vào cùng một định dạng, một trong hai thường bị ảnh hưởng. doc-builder của Hugging Face nhằm mục đích giải quyết sự căng thẳng này bằng cách cho phép tài liệu vẫn nguyên vẹn trong khi các ví dụ cơ bản của nó được xác thực nghiêm ngặt, đảm bảo rằng mọi đoạn mã mà người dùng gặp phải là một sự thật có thể kiểm chứng, chứ không chỉ là một khát vọng. Điều này rất quan trọng để duy trì uy tín và đẩy nhanh việc áp dụng của nhà phát triển trong thế giới AI phát triển nhanh chóng.

Di sản của `doctest`: Những đổi mới ban đầu và Nhu cầu phát triển

Khái niệm tài liệu có thể thực thi đã sớm thu hút sự chú ý trong Python với sự ra đời của doctest trong Python 2.1 (2001). Được tạo ra bởi Tim Peters, doctest là một giải pháp thanh lịch: nó phân tích các ví dụ tài liệu được định dạng giống như các phiên trình thông dịch Python tương tác (>>> add(2, 3)\n5) và xác minh rằng đầu ra khớp với kỳ vọng. Đổi mới này đã biến các ví dụ tài liệu thành các bài kiểm thử hồi quy tự động, một bước tiến đáng kể về chất lượng mã.

doctest đặc biệt phù hợp với Python, một ngôn ngữ khuyến khích khám phá tương tác. Đối với các dự án nhỏ và API đơn giản, nó hoạt động cực kỳ hiệu quả, cung cấp một cơ chế đơn giản nhưng mạnh mẽ để đảm bảo các ví dụ cơ bản vẫn hoạt động. Nó thể hiện tinh thần 'chỉ cho xem, đừng chỉ nói' trong phát triển phần mềm, biến tài liệu thành một phần tích cực của bộ kiểm thử.

Giải pháp hiện đại của Hugging Face: Các khối Markdown có thể chạy

Nhận thấy những hạn chế của các cách tiếp cận cũ đối với các dự án phức tạp, quy mô lớn, dự án doc-builder của Hugging Face giới thiệu một cách tiếp cận tinh vi đối với tài liệu có thể chạy. Thay vì nhúng các bài kiểm thử trong cú pháp tài liệu, nó coi các đoạn mã tài liệu là mã Python thông thường nằm trong Markdown. Điều này thực sự biến Markdown thành một vùng chứa kiểm thử mỏng, tách rời phần trình bày khỏi phương pháp kiểm thử.

Một khối có thể chạy trong Markdown trông như thế này:

```py runnable:quickstart
from transformers import pipeline

pipe = pipeline("sentiment-analysis")
result = pipe("I love runnable docs!")

if not result:  # doc-builder: hide
    raise ValueError("pipeline returned no result")

print(result[0]["label"])
assert result[0]["score"] > 0.5  # doc-builder: ignore-bare-assert
```

Khi được hiển thị, khối này xuất hiện dưới dạng một ví dụ mã tiêu chuẩn. Tuy nhiên, trong quá trình kiểm thử, nó được thực thi dưới dạng mã Python bình thường. Bản chất kép này đảm bảo tài liệu vẫn sạch sẽ cho người đọc trong khi cung cấp các ví dụ mạnh mẽ, có thể kiểm thử cho nhà phát triển. Cách tiếp cận này đặc biệt có tác động lớn đối với các lĩnh vực phức tạp như AI, nơi các ví dụ thường liên quan đến các bước tải và suy luận mô hình phức tạp.

Tích hợp liền mạch với `pytest` và các tính năng nâng cao

Một yếu tố khác biệt chính trong cách tiếp cận của Hugging Face là khả năng tích hợp liền mạch với các framework kiểm thử hiện đại, đặc biệt là pytest. Khi hf-doc-builder được cài đặt, pytest có thể tự động phát hiện và thực thi các khối có thể chạy trong các tệp Markdown, coi mỗi khối là một mục kiểm thử tiêu chuẩn. Điều này có nghĩa là các ví dụ tài liệu có thể tham gia đầy đủ vào cơ sở hạ tầng kiểm thử hiện có của dự án, tận dụng các tính năng mạnh mẽ của pytest như cơ chế xác nhận, fixture, công cụ gỡ lỗi và báo cáo toàn diện.

Sự phát triển của Tài liệu có thể thực thi: `doctest` so với `doc-builder`

Tính năng	`doctest` (Truyền thống)	`doc-builder` (Markdown có thể chạy hiện đại)
Cách tiếp cận kiểm thử	Nhúng các bài kiểm thử dưới dạng phiên trình thông dịch trong tài liệu	Coi các đoạn mã tài liệu là mã Python thông thường để kiểm thử
Tích hợp	Mô-đun thư viện tiêu chuẩn	Plugin `pytest` để tích hợp liền mạch
Cú pháp kiểm thử	Dấu nhắc `>>>`, so khớp đầu ra mong đợi	Mã Python tiêu chuẩn, xác nhận `pytest`
Tính linh hoạt	Hạn chế, so khớp đầu ra dễ vỡ	Cao, hỗ trợ các bài kiểm thử phức tạp, decorator, gỡ lỗi
Sự gọn gàng của tài liệu	Có thể làm lộn xộn tài liệu với các cơ chế kiểm thử	Giữ tài liệu gọn gàng với các chỉ thị ẩn
Gỡ lỗi	So sánh chuỗi, ít kiểm tra trực tiếp hơn	Gỡ lỗi Python tiêu chuẩn, dấu vết ngăn xếp đầy đủ
Thiết lập/Gỡ bỏ	Có thể thêm nhiễu vào ví dụ	Quản lý ngữ cảnh hiệu quả với các khối tiếp nối
Nguồn sự thật	Định dạng tài liệu và các bài kiểm thử được nhúng	Nguồn Markdown, được kiểm thử thông qua thực thi Python tiêu chuẩn

Ngoài ra, doc-builder còn giới thiệu các khối tiếp nối, một tính năng quan trọng cho các hướng dẫn nhiều bước. Chúng cho phép tác giả chia một ví dụ thành nhiều đoạn mã hiển thị, như runnable:test_basic theo sau bởi runnable:test_basic:2. Quan trọng là, các khối này chia sẻ cùng một ngữ cảnh thực thi trong quá trình kiểm thử, cho phép một luồng hướng dẫn tự nhiên mà không buộc tất cả mã vào một khối dài. Sự linh hoạt này rất quan trọng để hướng dẫn người dùng qua việc sử dụng mô hình AI phức tạp hoặc các quy trình xử lý dữ liệu.

Chẳng hạn, một quy trình làm việc phát triển tác nhân AI có thể bao gồm nhiều bước: định nghĩa công cụ của tác nhân, khởi tạo tác nhân và sau đó chạy một truy vấn. Các khối tiếp nối cho phép mỗi bước này được trình bày rõ ràng trong các phần tài liệu riêng biệt trong khi được thực thi như một chuỗi kiểm thử duy nhất, mạch lạc, tương tự như cách các quy trình làm việc tác nhân nâng cao được Vận hành AI tác nhân: Phần 1.

Duy trì tài liệu gọn gàng trong khi đảm bảo kiểm thử mạnh mẽ

Một trong những giải pháp thanh lịch nhất của doc-builder là khả năng giữ cho tài liệu được hiển thị sạch sẽ, ngay cả khi nguồn Markdown chứa các chỉ thị dành riêng cho kiểm thử. Các nhà phát triển có thể nhúng các nhận xét như # doc-builder: hide cho các dòng có thể thực thi nhưng không nên xuất hiện trong tài liệu, hoặc # doc-builder: ignore-bare-assert cho các xác nhận là một phần của bài kiểm thử nhưng nhận xét của chúng không nên được hiển thị. Tương tự, các decorator pytest (# pytest-decorator: ...) cũng bị loại bỏ trong quá trình hiển thị.

Điều này đảm bảo rằng tài liệu vẫn tập trung vào việc giảng dạy và sự rõ ràng, không bị lộn xộn bởi các đoạn mã kiểm thử mẫu. Người dùng chỉ thấy mã có liên quan, trong khi hệ thống bên dưới đảm bảo chức năng của nó. Sự cân bằng này rất quan trọng đối với tài liệu công cụ dành cho nhà phát triển, nơi cả tính thẩm mỹ và độ chính xác tuyệt đối đều là tối quan trọng.

Tác động đến các dự án AI quy mô lớn và hơn thế nữa

Đối với các kho lưu trữ khổng lồ như Transformers của Hugging Face, với hàng trăm trang tài liệu và hàng nghìn ví dụ, tính năng này mang tính biến đổi. Nó tự động hóa việc ngăn chặn lệch tài liệu, một vấn đề mà nếu không sẽ đòi hỏi nỗ lực thủ công rất lớn hoặc dẫn đến một luồng ví dụ bị hỏng liên tục. Tài liệu có thể chạy giúp giữ cho tài liệu và cơ sở mã được đồng bộ, duy trì độ tin cậy ở một quy mô mà việc xem xét thủ công đơn giản là không khả thi. Điều này phù hợp với những nỗ lực rộng lớn hơn trong cộng đồng AI để Đánh giá tác nhân AI cho sản xuất một cách nghiêm ngặt và đảm bảo độ tin cậy.

Bằng cách đưa tài liệu có thể thực thi vào kỷ nguyên hiện đại của pytest và các quy trình CI/CD tinh vi, Hugging Face thể hiện một cam kết mạnh mẽ đối với trải nghiệm nhà phát triển và chất lượng mã. Mục tiêu vẫn như cũ từ hơn hai thập kỷ trước: các ví dụ tài liệu phải hoạt động. Nhưng giờ đây, chúng không chỉ minh họa cách mã nên hoạt động mà còn liên tục chứng minh rằng nó hoạt động, thúc đẩy một hệ sinh thái phát triển AI đáng tin cậy và vững chắc hơn.

Nguồn gốc

https://huggingface.co/blog/huggingface/runnable-examples

Câu hỏi thường gặp

What is the core problem Hugging Face's runnable Markdown addresses?

Hugging Face's runnable Markdown addresses the pervasive problem of 'documentation drift,' where code examples in documentation become outdated and silently break as libraries and APIs evolve. This leads to user frustration and diminishes the credibility of the documentation. By making documentation examples runnable and testable, the doc-builder ensures that these snippets are continuously validated against the codebase, guaranteeing that they always work as advertised. This proactive approach prevents broken examples, enhances user trust, and improves the overall developer experience by providing reliable resources.

How does runnable Markdown differ from Python's traditional `doctest` module?

While both `doctest` and runnable Markdown aim for executable documentation, they differ significantly in their approach. `doctest` embeds tests directly into documentation syntax, requiring examples to mirror interactive interpreter sessions with expected output. This often leads to documentation being cluttered with test mechanics. Hugging Face's runnable Markdown, in contrast, treats documentation snippets as normal Python code living within Markdown files. It integrates seamlessly with modern testing frameworks like `pytest`, allowing for complex assertions, debugging, and standard test infrastructure. This separation of concerns ensures documentation remains clean and readable, while testing remains powerful and flexible, avoiding the limitations of `doctest`'s brittle output matching and verbose setup/teardown.

What are 'continuation blocks' in Hugging Face's `doc-builder`?

Continuation blocks are a powerful feature in Hugging Face's `doc-builder` that allow authors to split complex code examples or tutorials across multiple visible Markdown snippets while maintaining a shared execution context during testing. This means that a setup defined in one runnable block can be reused and built upon in a subsequent block, without forcing the documentation to present everything as one long, monolithic code fence. For example, `runnable:test_basic` can define initial variables, and `runnable:test_basic:2` can then use those variables. This enhances readability and instructional flow in documentation, making it easier to present multi-step processes without sacrificing the integrity of the underlying testable code.

How does `doc-builder` integrate with existing testing frameworks like `pytest`?

Hugging Face's `doc-builder` integrates natively with `pytest`, transforming runnable Markdown blocks into standard `pytest` test items. With `hf-doc-builder` installed, `pytest` automatically discovers and executes these blocks within Markdown files. This integration means that documentation examples can leverage the full power of `pytest`, including its assertion mechanisms, fixtures, decorators, and debugging tools. Failures appear as normal test failures with comprehensive tracebacks, allowing developers to debug effectively. This approach avoids the need for a special-purpose testing mini-language, embedding documentation tests directly into the project's existing, robust test infrastructure.

How does `doc-builder` ensure documentation remains clean despite embedded test logic?

A key design principle of `doc-builder` is to prevent test mechanics from polluting the user-facing documentation. Authors can embed test-only directives, such as `# pytest-decorator: transformers.testing_utils.slow` or `# doc-builder: hide` for lines that should be executable but not displayed, directly within the Markdown source. When the documentation is rendered, `doc-builder` intelligently strips these directives and comments, presenting a clean, readable code snippet to the user. This allows developers to write comprehensive tests alongside their examples without compromising the clarity and brevity expected of good documentation, maintaining a clear separation between the source code for testing and the rendered content for users.

What are the benefits of runnable documentation for large AI projects like Hugging Face Transformers?

For large AI projects such as Hugging Face Transformers, which involve extensive documentation and thousands of code examples, runnable documentation offers immense benefits. It drastically reduces 'documentation drift' by continuously validating examples against the evolving codebase, ensuring they remain accurate and functional. This prevents user frustration caused by broken examples and builds trust in the documentation's reliability. By integrating with `pytest`, it allows these projects to manage documentation tests within their existing CI/CD pipelines, making manual review of examples unnecessary at scale. This automated validation is crucial for maintaining the quality and usability of documentation in rapidly developing and complex software ecosystems.

Can runnable Markdown be adopted by other projects outside of Hugging Face?

Yes, the principles and mechanisms behind Hugging Face's runnable Markdown, particularly its integration with standard Python testing tools like `pytest` and its focus on separating testing logic from displayed documentation, are highly applicable and beneficial for any software project. While the `doc-builder` itself is specific to Hugging Face, the underlying ideas represent a best practice in developer tools. Other projects can implement similar systems using existing tools or adapt `doc-builder`'s concepts to ensure their documentation examples are continuously tested and reliable. This approach is a general solution to a common problem across the software development landscape, making documentation more robust and trustworthy.

Cập nhật tin tức

Nhận tin tức AI mới nhất qua email.

Chia sẻ