Phân loại kết quả CLI cục bộ với Verdict

Verdict thực hiện gì

Verdict là bản xem trước nghiên cứu về một lớp kết quả ngữ nghĩa dành cho các tác nhân lập trình, trình chạy CI và những hệ thống sử dụng công cụ khác. Thay vì xem mã thoát của quy trình là bằng chứng quyết định, công cụ phân tích đồng thời lệnh, mã thoát, đầu ra chuẩn và lỗi chuẩn.

Mô hình trả về một trong bốn nhãn: success, failure, blocked hoặc unknown. Sự phân biệt này hữu ích vì một lệnh có thể thoát với mã zero dù không chạy bài kiểm thử nào, trả về phản hồi HTTP 500, chờ một worker hoặc tạo ra đầu ra chưa hoàn chỉnh. Tương tự, mã thoát khác zero có thể cho thấy môi trường bị chặn thay vì một khẳng định kiểm thử thất bại.

Quan trọng: Verdict là một trình phân loại mang tính tư vấn. Công cụ không chứng minh rằng tác vụ đã hoàn tất hoặc môi trường đã thay đổi như dự kiến. Hãy tiếp tục dùng các kiểm tra xác định và việc xác minh trạng thái có thẩm quyền làm nguồn sự thật.

Tính năng chính

• Suy luận cục bộ: Dữ liệu đầu vào được xử lý trên CPU cục bộ mà không gọi mạng hoặc thu thập telemetry.
• Mô hình siêu nhỏ: Mô hình đã lượng tử hóa có kích thước khoảng 197 KB.
• Thời gian chạy không phụ thuộc: Suy luận sử dụng thư viện chuẩn Python và không cần tệp tokenizer, GPU hay các phụ thuộc thời gian chạy Python ngoài chính gói này.
• Phân loại ngữ nghĩa: Mô hình xem xét lệnh, mã thoát, stdout và stderr thay vì chỉ dựa vào mã thoát.
• Dự đoán nhanh: Kho lưu trữ báo cáo thời gian suy luận trung vị là 0.54 ms trong môi trường benchmark Windows 11, AMD64 và Python 3.12 được tài liệu hóa.
• Giao diện Python và CLI: Sử dụng mô hình trong ứng dụng hoặc trực tiếp từ pipeline shell.
• Minh họa trên trình duyệt: Trang dự án chạy cùng các trọng số đã lượng tử hóa trong trình duyệt mà không tải nhật ký lên.

Verdict sử dụng các 3–5-gram ký tự đã băm và 1–3-gram từ cùng hồi quy logistic đa lớp. Dữ liệu đầu vào là văn bản UTF-8, mỗi luồng đầu ra được giới hạn ở 12,288 ký tự bằng cách cắt rõ ràng phần đầu và phần cuối.

Hiểu bốn nhãn

• success: Đầu ra chứa bằng chứng tích cực cho thấy thao tác đã hoàn tất.
• failure: Thao tác đã chạy và báo cáo một lỗi cụ thể.
• blocked: Quyền, phụ thuộc, mạng, giới hạn quota hoặc môi trường đã ngăn việc thực thi.
• unknown: Bằng chứng không có, chưa đầy đủ, bị bỏ qua, chỉ giới hạn ở chạy thử hoặc không đủ để kết luận.

Các xác suất trả về đến từ một mô hình đa lớp tuyến tính. Không được diễn giải chúng là độ tin cậy đã hiệu chuẩn cho các quyết định quan trọng về an toàn.

Cài đặt Verdict

Sao chép kho lưu trữ, truy cập thư mục của kho và cài đặt gói bằng pip:

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

Thao tác này cài đặt gói Python verdict_tiny và giao diện dòng lệnh verdict.

Chạy dự đoán Python đầu tiên

Tạo một thực thể Verdict và truyền vào đó cùng bằng chứng mà trình chạy công cụ của bạn đã quan sát. Ví dụ này mô phỏng một quy trình pytest thành công nhưng thực tế không chạy bài kiểm thử nào:

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

Đầu ra mô hình được tài liệu hóa phân loại bằng chứng này là unknown, dù mã thoát bằng zero:

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

label là kết quả được chọn. Đối tượng probabilities cung cấp điểm số cho mọi lớp, còn advisory nhấn mạnh rằng dự đoán không phải bằng chứng có thẩm quyền.

Sử dụng Verdict từ dòng lệnh

Bạn có thể chuyển đầu ra của lệnh vào Verdict đồng thời cung cấp lệnh gốc và mã thoát:

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

Đối với đầu ra đã được lưu trong tệp, hãy sử dụng --stdout và --stderr:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

Bạn cũng có thể tải trọng số từ một vị trí cụ thể:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

Tích hợp Verdict an toàn

Một cách tích hợp thực tế nên xem Verdict là một tín hiệu bổ sung để ra quyết định, không phải trọng tài cuối cùng. Tác nhân lập trình hoặc trình chạy CI có thể sử dụng nhãn này để quyết định có cần kiểm tra thêm bằng chứng, thử lại thao tác hoặc yêu cầu con người xem xét hay không.

1. Chạy lệnh gốc và giữ lại mã thoát, stdout và stderr của lệnh.
2. Truyền mọi bằng chứng hiện có vào Verdict.
3. Kiểm tra cả nhãn được dự đoán và xác suất của các lớp.
4. Áp dụng các ngưỡng riêng của ứng dụng trước khi thực hiện hành động có hệ quả.
5. Xác minh việc hoàn tất bằng các kiểm tra xác định, chẳng hạn như số lượng bài kiểm thử, tệp được tạo, trạng thái API hoặc bản ghi cơ sở dữ liệu.

Ví dụ, kết quả unknown thường nên kích hoạt việc điều tra thêm thay vì tuyên bố đã hoàn tất. Kết quả blocked có thể là lý do để kiểm tra thông tin xác thực, phụ thuộc, kết nối, quyền hoặc quota trước khi thử lại. Kết quả success vẫn cần được xác minh có thẩm quyền khi tính đúng đắn là quan trọng.

Mẹo nâng cao

Bảo toàn đầy đủ ngữ cảnh thực thi

Bất cứ khi nào có thể, hãy cung cấp lệnh thực tế, mã thoát, stdout và stderr. Việc lược bỏ các luồng này có thể làm mất bằng chứng giúp phân biệt lỗi cụ thể với trở ngại môi trường hoặc một lần chạy không có kết luận.

Tính đến việc cắt ngắn đầu vào

Mỗi luồng đầu ra bị giới hạn ở 12.288 ký tự bằng cách cắt phần đầu và phần cuối. Khi nhật ký rất lớn, hãy đảm bảo các thông báo mang tính quyết định xuất hiện gần phần đầu hoặc phần cuối, hoặc thực hiện một lần quét xác định bổ sung trên toàn bộ nhật ký.

Đặt ngưỡng ra quyết định thận trọng

Các xác suất này không phải là mức độ tin cậy đã được hiệu chuẩn theo nghĩa an toàn trọng yếu. Hãy sử dụng các ngưỡng phù hợp với quy trình của bạn và chuyển các trường hợp không chắc chắn hoặc có hậu quả đáng kể sang các bước kiểm tra xác định hoặc đánh giá của con người.

Sử dụng trọng số tùy chỉnh hoặc đã tải xuống

Các trọng số lượng tử hóa được phát hành được lưu tại weights/verdict-q8.bin và cũng có sẵn trên Hugging Face. CLI chấp nhận đường dẫn trọng số thay thế thông qua --weights.

Thử bản demo trên trình duyệt

Trang dự án Verdict chạy cùng các trọng số lượng tử hóa trong trình duyệt. Theo tài liệu dự án, nhật ký không được tải lên.

Tái hiện quá trình huấn luyện và đánh giá

Cài đặt các gói bổ sung cho huấn luyện và phát triển, tạo lại kho ngữ liệu tổng hợp, huấn luyện mô hình, xuất trọng số int8, đánh giá tạo phẩm và chạy các bài kiểm thử:

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

Điểm chuẩn công khai sử dụng 192 ví dụ tổng hợp từ 48 nhóm CLI không xuất hiện trong quá trình huấn luyện. Quá trình huấn luyện sử dụng 1.440 ví dụ tổng hợp từ 60 nhóm khác nhau. Mô hình lượng tử hóa được báo cáo đạt độ chính xác 93,2% và macro-F1 93,2%, so với độ chính xác 47,9% và macro-F1 31,9% của mô hình cơ sở dựa trên mã thoát.

Kho ngữ liệu là dữ liệu tổng hợp và thiên về tiếng Anh. Các phép đo này đánh giá những mẫu được giữ lại để kiểm thử, không đánh giá độ tin cậy trên các dấu vết tác nhân trong môi trường sản xuất; kết quả về độ trễ cũng không phải là cam kết áp dụng cho mọi phần cứng.

Nắm rõ giới hạn của dự án

Verdict được thiết kế với phạm vi hẹp. Công cụ này phân loại bằng chứng quan sát được trong đầu ra CLI, nhưng không xác định liệu một tác vụ rộng hơn đã hoàn tất hay chưa. Công cụ cũng không chứng minh tính đúng đắn, an toàn hoặc trung thực của mã.

Vì vậy, dự án phù hợp nhất khi được sử dụng như một lớp ngữ nghĩa giữa quá trình thực thi thô và hành động tiếp theo của tác nhân. Công cụ có thể nhận diện những bằng chứng mà mã thoát bỏ sót, nhưng nên bổ trợ thay vì thay thế các bài kiểm thử, việc kiểm tra trạng thái, quy tắc xác thực và phán đoán của con người.

Kết luận

Verdict cung cấp một cách nhỏ gọn, nhanh và cục bộ để diễn giải kết quả CLI cẩn trọng hơn so với việc chỉ kiểm tra mã thoát. Hãy cài đặt công cụ dưới dạng gói Python, cung cấp đầy đủ ngữ cảnh thực thi và sử dụng bốn nhãn của công cụ để định hướng các hành động tiếp theo. Để tự động hóa đáng tin cậy, luôn kết hợp kết quả mang tính khuyến nghị của công cụ với việc xác minh mang tính xác định và có thẩm quyền.