Xây dựng vòng lặp khôi phục tác tử an toàn hơn với Dot Reflex 14B

Dot Reflex 14B thực hiện những gì

Dot Reflex 14B là bộ điều khiển khôi phục thực thi dành cho các tác nhân lập trình và sử dụng công cụ. Nó không thay thế tác nhân thực hiện công việc. Thay vào đó, nó xem xét bản tóm tắt JSON ngắn gọn về tiến trình của tác nhân và đề xuất cách bộ điều phối xung quanh nên kiểm soát giai đoạn thực thi tiếp theo.

Bộ điều khiển có thể giám sát các tác nhân được vận hành bởi GPT, Claude, Gemini, Qwen, Llama hoặc một mô hình khác vì nó hoạt động trên các sự kiện thực thi đã chuẩn hóa thay vì kiến trúc nội bộ của mô hình thực hiện. Bản phát hành này là một bộ điều hợp QLoRA rank-64 cho Qwen3-14B-Base.

Dot Reflex trả về một trong mười hành động:

• continue: cho phép tiếp tục một kế hoạch hợp lý.
• verify: yêu cầu bằng chứng cho một nhận định hoặc giả định rủi ro.
• retry_differently: lặp lại lần thử ngay trước đó bằng một lệnh, tham số hoặc phương pháp khác.
• replan: thay thế cách tiếp cận có các giả định cốt lõi đã thất bại.
• rollback: khôi phục trạng thái đã biết là tốt sau một thay đổi gây hại.
• branch: cô lập nhiều cách tiếp cận khả dĩ trong các môi trường riêng biệt.
• switch_model: chuyển lần thử tiếp theo sang một mô hình khác sau lỗi dai dẳng về năng lực hoặc nhà cung cấp.
• ask_human: tạm dừng khi cần quyền hạn, bí mật, làm rõ thông tin hoặc quyết định bên ngoài.
• stop_successfully: hoàn tất khi có đủ bằng chứng hỗ trợ cho việc hoàn thành.
• stop_failure: dừng khi không còn cách khôi phục an toàn và được cấp quyền.

Đầu ra là một đề xuất, không phải sự cấp phép. Bộ điều phối của bạn vẫn chịu trách nhiệm về quyền hạn, thực thi chính sách, thực thi công cụ, cơ chế khôi phục và quyết định cuối cùng về việc dừng.

Tính năng chính

• Đầu vào trung lập với framework: Bộ điều khiển tiếp nhận JSON thông thường được tổng hợp từ các sự kiện thực thi đã được framework tác nhân ghi lại.
• Đầu ra máy đọc được: Mọi phản hồi hợp lệ đều chứa một hành động, lý do, giá trị độ tin cậy, hướng dẫn khôi phục và trạng thái phân tích.
• Sinh tất định: Runtime tham chiếu sử dụng phương thức sinh tham lam.
• Hành vi đóng khi lỗi: CLI thoát với trạng thái khác không khi lược đồ đầu vào hoặc hành động được sinh không hợp lệ.
• Nhiều giao diện: Chạy một quyết định từ dòng lệnh, truyền JSON qua đầu vào chuẩn hoặc lưu trữ một endpoint HTTP cục bộ.
• Giám sát đa mô hình: Tác nhân thực hiện không cần sử dụng Qwen hoặc dùng chung kiến trúc với bộ điều khiển.

Yêu cầu và cài đặt

Runtime tham chiếu 4-bit yêu cầu Linux và GPU NVIDIA. GPU 24 GB là mức tối thiểu thực tế cho từng yêu cầu một lần, trong khi 40–48 GB cung cấp thêm dung lượng dự phòng. Bản phát hành này không bao gồm các bản dựng GGUF, Ollama, MLX, CPU hoặc trọng số đã hợp nhất.

Sao chép kho lưu trữ, tạo môi trường ảo Python và cài đặt các phần phụ thuộc runtime:

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

Kho GitHub chứa runtime, các bài kiểm thử, ví dụ, tài liệu và biên nhận đánh giá. Bộ điều hợp có dung lượng khoảng 1.03 GB được lưu trữ trên Hugging Face và tự động tải xuống khi sử dụng lần đầu. Các trọng số cơ sở Qwen3 được ghim phiên bản cũng được Hugging Face tải xuống và lưu vào bộ nhớ đệm.

Xác minh bản phát hành

Từ thư mục gốc của kho lưu trữ, hãy xác minh payload mã nguồn trên Linux:

sha256sum --check SHA256SUMS

Trên macOS, sử dụng lệnh tương đương bên dưới. Lưu ý rằng macOS không được liệt kê là nền tảng được hỗ trợ cho runtime GPU tham chiếu.

shasum -a 256 -c SHA256SUMS

Bạn có thể xác thực manifest mã nguồn, danh tính cơ sở được ghim phiên bản, các ví dụ JSON, lược đồ và biên nhận biểu đồ mà không cần tải mô hình:

python3 scripts/validate_release.py

Chuẩn bị tiến trình của tác nhân

Dot Reflex yêu cầu một ảnh chụp nhanh ngắn gọn thay vì bản ghi thô. Hợp đồng đầu vào chính xác được định nghĩa trong trajectory.schema.json. Hầu hết hệ thống tác nhân cần một bộ chuyển đổi nhỏ để ánh xạ các sự kiện đặc thù của framework vào cấu trúc này.

Ví dụ, giả sử một tác nhân chỉnh sửa mã đặt lại mật khẩu và tuyên bố hoàn tất mà không chạy kiểm thử. Một tiến trình có thể trông như sau:

{
  "task_summary": "Thêm bước xác thực token đặt lại mật khẩu",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Đã sửa đổi auth/reset.py và tuyên bố hoàn tất.",
      "result": "Đã áp dụng bản vá; chưa chạy xác minh."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Các bài kiểm thử chưa từng được thực thi."
    }
  ],
  "current_state": "Mã đã thay đổi nhưng không có bằng chứng cho thấy mã hoạt động.",
  "detected_failure_signals": ["false_completion_risk"]
}

Sau đó, bộ điều khiển có thể xác định bằng chứng còn thiếu và trả về một quyết định có cấu trúc như sau:

{
  "action": "verify",
  "rationale": "Tác nhân đã tuyên bố hoàn tất mà không có bằng chứng từ kiểm thử.",
  "confidence": 0.98,
  "recovery_instructions": "Chạy các bài kiểm thử token đặt lại mục tiêu, sau đó chạy bộ kiểm thử auth liên quan.",
  "parse_valid": true
}

Chỉ đưa vào những bằng chứng mà bộ điều phối của bạn có thể hỗ trợ chính xác. Các sự kiện bị thiếu, lỗi thời hoặc gây hiểu lầm có thể dẫn đến đề xuất không chính xác.

Chạy một quyết định cơ bản

Kho lưu trữ bao gồm một quỹ đạo mẫu cho kịch bản hoàn tất giả. Gửi quỹ đạo đó đến CLI one-shot:

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

Bạn cũng có thể truyền một quỹ đạo qua đầu vào tiêu chuẩn bằng cách sử dụng - làm đường dẫn đầu vào:

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

Trong một trình điều phối, hãy kiểm tra cả trạng thái thoát của tiến trình và trường parse_valid được trả về. Trạng thái thoát khác 0 cho biết lược đồ đầu vào hoặc hành động được tạo không hợp lệ và phải ngăn việc tiếp tục tự động.

Chạy Dot Reflex dưới dạng Dịch vụ HTTP Cục bộ

Cài đặt các phần phụ thuộc bổ sung cho máy chủ và khởi chạy ứng dụng FastAPI bằng Uvicorn:

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

Gửi cùng quỹ đạo đến endpoint quyết định:

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

Ví dụ này liên kết với localhost. Trước khi đưa dịch vụ ra mạng, hãy bổ sung xác thực, TLS, giới hạn tốc độ, giới hạn kích thước yêu cầu và ghi nhật ký kiểm toán.

Tích hợp Bộ điều khiển vào Vòng lặp Tác tử

Gọi Dot Reflex tại các điểm kiểm tra bằng chứng có ý nghĩa thay vì sau mỗi token được tạo. Các điểm kiểm tra hữu ích bao gồm lần gọi công cụ thất bại, hành động lặp lại, chỉnh sửa mã, kết quả kiểm thử hoặc bản dựng, thay đổi môi trường hay tuyên bố hoàn tất.

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

Mẫu này giúp tách biệt các trách nhiệm. Dot Reflex phân loại nhu cầu khôi phục, còn bộ điều phối triển khai thao tác thực tế. Ví dụ, khuyến nghị rollback chỉ nên gọi một nguyên hàm rollback mà bộ điều phối đã định nghĩa và cấp quyền từ trước.

Bộ điều khiển có thể kết nối với LangGraph, OpenAI Agents SDK, OpenHands, AutoGen, CrewAI, Google ADK hoặc một vòng lặp công cụ tùy chỉnh bằng cách chuẩn hóa các sự kiện của chúng. Đây không phải là phần mềm trung gian cắm là chạy cho Cursor, Claude Code, Codex CLI hoặc Aider, trừ khi có wrapper hoặc hook thu thập các luồng sự kiện của chúng. Tham khảo INTEGRATION.md để xem các ví dụ ánh xạ và ghi chú về khả năng tương thích.

Mẹo Tích hợp Nâng cao

Sử dụng Kiểm tra Xác minh Mang tính Quyết định Nhỏ nhất

Khi hành động là verify, hãy ưu tiên bước kiểm tra hẹp nhất có khả năng xác nhận hoặc bác bỏ tuyên bố. Trong quy trình lập trình, đó có thể là chạy các bài kiểm thử có mục tiêu trước khi chạy bộ kiểm thử lớn hơn. Ghi lại kết quả và gửi một quỹ đạo mới tại điểm kiểm tra bằng chứng tiếp theo.

Ánh xạ Rõ ràng Mọi Hành động

Không xem các hành động không xác định hoặc không được hỗ trợ là continue. Định nghĩa hành vi của bộ điều phối cho cả mười hành động, xác thực hành động được tạo và dừng an toàn khi việc phân tích cú pháp hoặc kiểm tra chính sách thất bại.

Cung cấp các Nguyên hàm Khôi phục Thực tế

Khuyến nghị chỉ hữu ích nếu bộ điều phối có thể thực thi chúng. Hệ thống hỗ trợ branch nên tạo worktree hoặc sandbox biệt lập. Hệ thống hỗ trợ rollback nên duy trì các trạng thái có thể khôi phục và đã biết là tốt. Bộ định tuyến đa mô hình cần có cơ chế định tuyến thực tế để triển khai switch_model.

Để Con người Kiểm soát các Quyết định Nhạy cảm

Sử dụng ask_human khi tác tử thiếu thẩm quyền, bí mật, thông tin làm rõ hoặc một quyết định từ bên ngoài. Không bao giờ cho phép riêng đầu ra của mô hình cấp quyền cho các hành động mang tính hủy hoại, tài chính, y tế, pháp lý, nhạy cảm về bảo mật hoặc có tác động lớn theo bất kỳ cách nào khác.

Hiệu chỉnh Độ tin cậy theo Môi trường Cục bộ

Giá trị confidence được trả về là văn bản do mô hình tạo ra, không phải một bảo đảm an toàn. Hãy đo lường và hiệu chỉnh lại giá trị này bằng các quỹ đạo đại diện cho môi trường của chính bạn trước khi áp dụng ngưỡng hoặc chính sách tự động hóa.

Bảo toàn Bằng chứng và Dấu vết Kiểm toán

Lưu trữ quỹ đạo đầu vào, phản hồi của bộ điều khiển, hành động khôi phục đã thực thi và kết quả tiếp theo. Các biên nhận này giúp điều tra lỗi dễ dàng hơn và hỗ trợ đánh giá xem bộ điều khiển có chuyển giao hiệu quả sang khối lượng công việc của bạn hay không.

Hiểu các Ranh giới Đánh giá

Dot Reflex được huấn luyện trên 6,000 quỹ đạo tổng hợp và được xác thực trên 600 quỹ đạo tổng hợp. Bài đánh giá Agent Recovery Bench v0 được công bố bao gồm 1,000 quỹ đạo tổng hợp cân bằng được giữ lại để đánh giá và 200 tập phục hồi tổng hợp có trạng thái riêng biệt.

Adapter đạt độ chính xác phục hồi 1.000, macro F1 1.000 và khả năng phục hồi mô phỏng 1.000 trên bài điểm chuẩn tổng hợp đó. Độ trễ trung bình được báo cáo là 6.13 giây trên NVIDIA H200, nhưng đây là phép đo cụ thể của một lần chạy chứ không phải tuyên bố phục vụ mang tính phổ quát.

Kết quả tổng hợp 100% không chứng minh độ tin cậy phổ quát. Điểm chuẩn này không phải SWE-bench, không phải bài kiểm thử giải quyết vấn đề kho lưu trữ đầu cuối và cũng không phải thử nghiệm trong môi trường sản xuất.

Dữ liệu đã công bố cho thấy mức độ phù hợp với phân phối benchmark, không chứng minh khả năng chuyển giao đáng tin cậy sang các lỗi do bên độc lập biên soạn hoặc lỗi trong môi trường production. Hãy xem EVALUATION.md trước khi trích dẫn kết quả hoặc thiết kế chính sách triển khai.

Chi tiết mô hình và môi trường chạy

• Mô hình cơ sở: Qwen/Qwen3-14B-Base.
• Phương pháp: QLoRA NF4 4-bit với tính toán BF16.
• Cấu hình LoRA: rank 64, alpha 128 và dropout 0.05.
• Các module mục tiêu: các lớp chiếu attention và MLP.
• Ngữ cảnh huấn luyện: 2.048 token.
• Tham số có thể huấn luyện: 256,901,120, tương đương 1.710% mô hình cơ sở.
• Giấy phép: Apache-2.0 cho repository và các tệp adapter.

Mô hình Qwen cơ sở là một dependency upstream riêng biệt. Hãy xem model card và giấy phép của mô hình trước khi phân phối hoặc triển khai hệ thống kết hợp.

Kết luận

Dot Reflex 14B bổ sung một lớp khôi phục có cấu trúc cho các vòng lặp thực thi agent. Hãy bắt đầu bằng cách cài đặt môi trường chạy GPU, chuyển đổi các sự kiện hiện có sang schema trajectory và kiểm thử một quyết định thông qua CLI. Sau đó, bạn có thể thêm dịch vụ HTTP hoặc gọi bộ điều khiển tại các cổng bằng chứng trong một harness tùy chỉnh. Hãy giữ quyền thực thi trong harness, xác thực mọi phản hồi, bảo toàn bằng chứng kiểm toán và đánh giá hiệu năng trên workload của riêng bạn trước khi bật tự động hóa.