Hướng dẫn này dành cho fork hiện tại, cập nhật ngày 09/09/2026. Đi theo thứ tự: cài công cụ → clone → setup → kiểm tra → mock → model thật → đọc log.
Tất cả lệnh bên dưới chạy tại thư mục inspect_ai. Dùng python3 run.py
trên Ubuntu/WSL hoặc python run.py trên PowerShell. Launcher chọn đúng venv
và đặt working directory về repo, kể cả khi terminal đang kích hoạt venv khác.
eval_agent/
├── inspect_ai/
│ ├── run.py # setup, doctor, build, test và chạy
│ ├── .env # key riêng của bạn
│ ├── .env.example # mẫu cấu hình
│ ├── agent_benchmark/ # agent registry, local tasks, Docker
│ │ ├── requirements.txt # dependency bổ sung của profile coding
│ │ └── .venv/ # Inspect + SDK mới, do launcher chọn
│ ├── rag_eval/ # corpus, retrieval, task RAG
│ │ └── .venv-ragchecker/ # worker RAGChecker, do task tự chọn
│ ├── src/inspect_ai/ # framework và scorer integration
│ ├── requirements.txt # dependency lõi của framework
│ └── logs-*/ # kết quả từng nhóm eval
└── RAGChecker/ # source upstream, cài editable vào worker
Hai environment phục vụ hai tiến trình có dependency khác nhau. Inspect
Agent Bridge cần anthropic>=1.0; RefChecker 0.2.17 cần
anthropic>=0.29,<0.30. LiteLLM trong worker còn có thể yêu cầu openai<3,
trong khi provider OpenRouter của checkout này cần openai>=3.1.
run.py setup quản lý việc cài. Không cần tạo thêm .venv cấp workspace,
kích hoạt venv thủ công hay cài .[dev] để chạy benchmark. Các file
requirements-dev/doc/dist/math.txt thuộc phát triển framework, không phải
những bước setup bổ sung của người chạy eval.
| Lệnh | Mục đích |
|---|---|
python3 run.py setup coding |
Cài Inspect, inspect-swe, inspect-evals và SDK mới |
python3 run.py setup rag |
Cài worker RAGChecker và spaCy model |
python3 run.py setup all |
Cài cả hai, giữ hai dependency graph riêng |
python3 run.py doctor all |
Kiểm tra dependency, runtime SDK và spaCy |
python3 run.py build |
Build Docker image của local coding tasks |
python3 run.py test |
Chạy unit test của local coding harness |
python3 run.py coding agents |
Liệt kê agent |
python3 run.py inspect ... |
Chạy Inspect CLI trong profile coding |
python3 run.py retrieval ... |
Đo retrieval offline |
python3 run.py worker ... |
Chạy Python trong worker khi cần chẩn đoán |
Setup có thể tải nhiều dependency ML của RefChecker. Chạy coding và retrieval keyword không cần setup worker. Setup không tự chạy model trả phí.
Ví dụ cho Ubuntu 24.04+, Python 3.12 trở lên:
sudo apt update
sudo apt install -y git python3 python3-venv python3-pip nodejs npm
git --version
python3 --version
node --version
npm --versionCài Docker Engine và Compose theo hướng dẫn Ubuntu của Docker. Nếu đã có Docker thì kiểm tra trước, không cài chồng hai bộ Docker khác nguồn:
docker --version
docker compose version
docker infoNếu daemon chạy nhưng tài khoản chưa truy cập được socket Docker:
sudo usermod -aG docker "$USER"Đăng xuất/đăng nhập lại rồi thử docker info. Nhóm Docker có quyền rất cao
trên host; chỉ thêm tài khoản tin cậy.
Clone và setup:
Các lệnh mới cần bản fork có run.py. Thay đổi của lần cập nhật này đang ở
checkout local, chưa được commit/push tự động. Khi chuyển sang máy khác,
hãy đưa thay đổi lên branch của bạn hoặc copy source đã cập nhật trước;
clone một revision cũ chưa có launcher sẽ không chạy được các lệnh này.
mkdir -p "$HOME/eval_agent"
cd "$HOME/eval_agent"
git clone https://github.com/VieHung/inspect_ai.git
git clone https://github.com/amazon-science/RAGChecker.git
cd inspect_ai
python3 run.py setup all
python3 run.py doctor all
python3 run.py build
python3 run.py testChỉ chạy SWE-bench/local coding: thay setup all, doctor all bằng
setup coding, doctor coding. SWE-bench dùng image riêng của từng sample;
build ở trên chỉ cần cho local coding tasks.
Repo đã clone thì vào checkout hiện có, không clone đè lên thư mục. Ở máy đang làm việc:
cd /home/taviethung/Storage_2/Work/Company/MB/testmbevalagent/inspect_ai
python3 run.py doctor allNếu nguồn RAGChecker nằm ở chỗ khác:
RAGCHECKER_DIR=/duong/dan/RAGChecker python3 run.py setup ragĐể chạy Linux sandbox thuận tiện, có thể dùng Ubuntu trong WSL2 và làm theo
mục Ubuntu. Cài Docker Desktop,
bật WSL integration, kiểm tra
docker info ngay trong Ubuntu. Venv Linux phải được tạo trong Linux.
Nếu chạy trực tiếp bằng PowerShell, cài Git, Python, Node.js và Docker Desktop:
winget install --exact --id Git.Git
winget install --exact --id Python.Python.3.13
winget install --exact --id OpenJS.NodeJS.LTS
winget install --exact --id Docker.DockerDesktopMở terminal mới, khởi động Docker Desktop ở chế độ Linux containers:
git --version
python --version
node --version
npm --version
docker compose version
docker info
New-Item -ItemType Directory -Force "$HOME\eval_agent"
Set-Location "$HOME\eval_agent"
git clone https://github.com/VieHung/inspect_ai.git
git clone https://github.com/amazon-science/RAGChecker.git
Set-Location inspect_ai
python run.py setup all
python run.py doctor all
python run.py build
python run.py testKhông cần Activate.ps1 hoặc thay execution policy để dùng run.py.
Những lệnh python3 run.py ... ở các mục tiếp theo đổi thành
python run.py ... và viết trên một dòng trong PowerShell. Bash nối dòng
bằng \; PowerShell không dùng ký tự đó để nối dòng.
Copy .env.example thành .env nếu chưa có, rồi điền key bằng editor.
Giữ file key hiện có nếu đã cấu hình.
OPENROUTER_API_KEY=your-openrouter-key
INSPECT_EVAL_MODEL=openrouter/deepseek/deepseek-v4-flash-0731
INSPECT_LOG_DIR=./logsĐây là model ID đang dùng trong workflow; quyền truy cập/khả dụng của model
phải được xác nhận bằng một sample thật. Thay --model nếu tài khoản dùng
model khác. Biến đã export trong shell có thể ưu tiên hơn file .env.
Task RAG copy OPENROUTER_API_KEY sang OPENAI_API_KEY cho RefChecker nếu
biến sau chưa được đặt. Nếu đã có OPENAI_API_KEY của dịch vụ khác, đặt lại
đúng OpenRouter key khi dùng endpoint OpenRouter. Không in key vào log.
python3 run.py doctor coding
python3 run.py coding agents
python3 run.py retrieval --k 5 --show-misses
python3 run.py inspect eval rag_eval/rag_task.py -T retriever=bm25 -T answer_scorer=keywords --model mockllm/model --limit 1 --log-dir ./logs-rag-mockLệnh retrieval chạy không cần API hay Docker. Lệnh RAG mock kiểm tra retrieve → generate giả → scorer → log; không đo chất lượng model thật.
Để kiểm tra agent CLI trong Docker:
python3 run.py build
python3 run.py coding run --agent opencode --model mockllm/model --limit 1 --max-sandboxes 1 --sandbox-prebuilt --log-dir ./logs-coding-mockMock không phát sinh inference trả phí, nhưng lần đầu có thể cần tải binary OpenCode hoặc image. Điểm 0 có thể là do mock không sửa code; kiểm tra sample hoàn tất và không có infrastructure error trước khi diễn giải điểm.
Luồng: dataset Hugging Face → Docker image từng issue → OpenCode sửa
/testbed → verifier SWE-bench → log Inspect. Mini hiện chứa 50 sample;
--max-sandboxes 1 giới hạn số sandbox đồng thời, không giới hạn dataset.
Chạy thử một sample:
python3 run.py inspect eval inspect_evals/swe_bench_verified_mini \
--solver inspect_swe/opencode -S cwd=/testbed -S version=1.18.29 \
--model openrouter/deepseek/deepseek-v4-flash-0731 \
--limit 1 --max-sandboxes 1 --message-limit 200 \
--token-limit 400000 --time-limit 1800 --log-dir ./logs-swebench-smokeKhi sample đã hoàn tất và chi phí phù hợp, chạy toàn bộ mini:
python3 run.py inspect eval inspect_evals/swe_bench_verified_mini \
--solver inspect_swe/opencode -S cwd=/testbed -S version=1.18.29 \
--model openrouter/deepseek/deepseek-v4-flash-0731 \
--max-sandboxes 1 --message-limit 200 \
--token-limit 400000 --time-limit 1800 --log-dir ./logs-swebenchToken/message/time limit là giới hạn mỗi sample, không phải tổng ngân sách cả 50 sample. Lệnh này không đặt trần USD. Không lấy việc setup thành công làm bằng chứng provider hoặc verifier đã chạy.
Không truyền --approval trong các lệnh benchmark chuẩn. Khi không có policy,
agent chạy tự động và các lần chạy có thể so sánh được. Nếu thêm
--approval human hoặc file policy, Inspect sẽ chặn tool call trước khi thực
thiện; sample có thể đứng chờ người duyệt, bị reject/terminate, hoặc hết
--time-limit. Điều này làm thay đổi trajectory, số tool call, thời gian và
điểm verifier, nên không nên trộn run có approval với run autonomous khi so
sánh model.
Approval được ghi thành event trong log, nhưng thời gian chờ người duyệt vẫn
có thể làm benchmark không còn là phép đo throughput tự động. --notification
chỉ gửi thông báo cho interaction; nó không tự approve. Permission nội bộ của
OpenCode (nếu có) là lớp riêng và không được suy ra từ --approval của Inspect.
Local coding dùng các task tại agent_benchmark/tasks, khác SWE-bench:
python3 run.py coding run --agent opencode --model openrouter/deepseek/deepseek-v4-flash-0731 --limit 1 --max-sandboxes 1 --sandbox-prebuilt --log-dir ./logs-codingXem README coding để chọn agent, custom factory, giới hạn và thêm task.
RAG keyword:
python3 run.py inspect eval rag_eval/rag_task.py -T retriever=lsa -T answer_scorer=keywords --model openrouter/deepseek/deepseek-v4-flash-0731 --limit 1 --log-dir ./logs-ragRAGChecker dùng worker riêng, vẫn gọi bằng cùng launcher:
python3 run.py setup rag
python3 run.py doctor rag
python3 run.py inspect eval rag_eval/rag_task.py -T retriever=lsa -T answer_scorer=ragchecker -T rag_metrics=overall_metrics --model openrouter/deepseek/deepseek-v4-flash-0731 --limit 1 --max-samples 1 --log-dir ./logs-ragcheckerRefChecker gọi model thêm để extract/check claims. Token/cost usage của
worker chưa cộng vào usage của model sinh đáp án trong log Inspect.
--model mockllm/model chỉ thay generator; scorer RAGChecker vẫn gọi
model thật nếu giữ cấu hình grader. Chi tiết ở README RAG.
python3 run.py inspect view --log-dir ./logs-swebenchMở URL localhost mà viewer in ra. Kiểm tra status, số sample hoàn tất,
sample error, score/verifier và token/time usage. status=success không
đồng nghĩa mọi sample giải đúng.
Retry log bị lỗi, thay đường dẫn bằng file có thật:
python3 run.py inspect eval-retry ./logs-swebench/your-run.evalRetry có thể tiếp tục phát sinh model calls. Giữ log cũ để đối chiếu.
Đừng ngắt khi Inspect đang Cleaning up Docker environments.
| Hiện tượng | Nguyên nhân / bước xử lý |
|---|---|
agent bridge requires ... anthropic ... 0.29.2 |
Dùng nhầm venv chứa RefChecker. Chạy python3 run.py doctor coding, rồi run.py inspect .... |
OpenRouter yêu cầu openai>=3.1 |
Profile coding bị cài chồng LiteLLM/Harbor. Không nâng đè SDK rồi bỏ qua pip check; dùng profile đúng. |
aiobotocore ... botocore mismatch trong worker |
LiteLLM mới kéo boto3 quá mới. python3 run.py setup rag resolve chung với LiteLLM 1.97.0, aioboto3 15.5.0, boto3 1.40.61 đã kiểm chứng. |
RAGChecker environment not found |
Chạy run.py setup rag. Task tự tìm worker ở rag_eval/.venv-ragchecker. |
spaCy en_core_web_sm thiếu |
Chạy lại run.py setup rag; kiểm tra bước pip trước bước tải spaCy. |
No services to build, using local image |
Không phải lỗi: image đã có, không có service cần build. |
Loading/Saving dataset mỗi lần |
Revision-pinned dataset có thể nạp raw cache rồi ghi processed cache; progress text không chứng minh tải lại toàn bộ. |
No space left on device |
Kiểm tra cả Docker, containerd, HF cache; xem phần disk bên dưới. |
pytest: unrecognized arguments --dist |
Dùng run.py test, đã vô hiệu hóa addopts dev của framework. |
No module named moto khi chạy tests toàn repo |
Bạn đang chạy suite phát triển framework, khác run.py test; cần môi trường dev riêng nếu phát triển core. |
| 401/403/model not found | Kiểm tra key, model ID và quyền provider bằng một sample; không phải lỗi dataset. |
| 429 hoặc timeout | Đọc sample error; giảm concurrency, kiểm tra provider, cân nhắc retry log. |
| mock 0 điểm | Xem sample/verifier hoàn tất chưa; không kết luận setup lỗi chỉ từ score. |
requirements...txt không tìm thấy |
Kiểm tra thư mục hiện tại, dùng run.py và đúng cú pháp Bash/PowerShell. |
| host trace/samplebuffer read-only | Kiểm tra quyền thư mục Inspect của người chạy; --log-dir không đổi toàn bộ đường dẫn nội bộ. |
Đo disk trước khi thay đổi cấu hình:
df -h
docker info --format '{{.DockerRootDir}}'
docker system df
sudo du -sh /var/lib/docker /var/lib/containerdMáy có thể đã di chuyển Docker/containerd sang ổ khác; dùng đường dẫn runtime
thực tế. Không tự xóa cache hoặc docker system prune -a để chữa dependency.
Nếu venv cũ bị trộn nhiều package, tạo lại chỉ profile đó sau khi dừng eval.
Đổi tên thư mục venv để giữ backup, rồi chạy run.py setup coding hoặc
setup rag. Venv đã đổi tên chỉ là backup; shebang có đường dẫn tuyệt đối,
không coi nó là môi trường có thể chạy tại vị trí mới. Không xóa log/source.
Harbor là workflow tùy chọn chưa nằm trong setup chuẩn này. Recipe cũ ép
openai>=3.1 lên môi trường LiteLLM yêu cầu openai<3 không chứng minh
tương thích. Recipe cũ đã chuyển thành ghi chú Harbor.
Cần một thiết kế tích hợp và kiểm chứng riêng trước khi đưa Harbor vào luồng
“từ đầu đến cuối”.
Tài liệu mô tả source hiện tại. Kết quả kiểm tra cụ thể của lần cập nhật được ghi tại validation; phân biệt kiểm tra offline, cài dependency thật, Windows và model thật. Một luồng chưa kiểm chứng không được xem là đã chạy thành công.