Iris
chính thứcMáy chủ đánh giá và quan sát tác nhân gốc MCP với ghi nhật ký theo dõi, đánh giá chất lượng đầu ra, theo dõi chi phí, 12 quy tắc đánh giá tích hợp sẵn, bảng điều khiển thời gian thực và phát hiện PII
Bạn có thể làm gì với Iris MCP?
- Ghi nhật ký và chấm điểm một lượt chạy — Yêu cầu trợ lý ghi nhật ký một lượt chạy của tác tử vào Iris và đánh giá đầu ra, sau đó xem kết luận và điểm số trên bảng điều khiển.
- Kiểm tra quy tắc an toàn và chi phí — Chạy 28 quy tắc xác định tích hợp sẵn để phát hiện PII, prompt injection, dấu hiệu ảo giác và ngưỡng chi phí mà không cần gọi LLM.
- Kiểm tra và chỉnh sửa quy tắc — Liệt kê các quy tắc tích hợp sẵn và xem xét hoặc thay đổi chúng, vì mọi quy tắc đều có thể kiểm tra và chỉnh sửa.
- Thêm quy tắc tùy chỉnh — Tải các quy tắc bạn viết dưới dạng mã thông qua
eval.pluginstrongconfig.json, được cố định bằng hàm băm tệp. - So sánh các lượt chạy — Mở hai lượt chạy trên cùng các câu hỏi cạnh nhau, kèm theo một khoảng thời gian, trong chế độ xem Runs trên bảng điều khiển.
- Chặn CI dựa trên kết luận — Chạy
ingestvới--evaluate --fail-on anyđể khiến một tác vụ thất bại nếu có bất kỳ kết luận nào không phải là đạt.
Tài liệu
Iris — đừng phát hành agent chỉ dựa vào cảm tính
Gửi Iris một lượt chạy của agent và yêu cầu đánh giá chất lượng, độ an toàn và chi phí — ngay trên máy của bạn, không cần SDK hay tài khoản. Hầu hết dự án agent kiểm tra chất lượng bằng cách chạy vài prompt quen thuộc rồi xem qua kết quả. Iris thay thế cách đó bằng những con số bạn có thể kiểm tra: các lượt chạy của agent được lưu vào cơ sở dữ liệu SQLite trên đĩa của bạn; 28 quy tắc tích hợp sẵn chấm điểm một cách xác định — PII, prompt injection, dấu hiệu ảo giác, ngưỡng chi phí và các lệnh gọi công cụ của chính agent — miễn phí, không gọi LLM; còn một giám khảo LLM tùy chọn với giới hạn chi phí cứng cho mỗi lần đánh giá sẽ xử lý các câu hỏi ngữ nghĩa. Mọi quy tắc đều có thể kiểm tra và chỉnh sửa, vì một giám khảo bạn không thể kiểm tra thì cũng chỉ là cảm tính được gắn một con số. Cấp phép MIT, không đo từ xa. Không có gì rời khỏi máy của bạn trừ khi bạn bật một trong các tùy chọn sau: một điểm cuối OpenTelemetry (IRIS_OTEL_ENDPOINT), xuất trace đến collector bạn chỉ định; giám khảo LLM dùng khóa của bạn, gửi văn bản được đánh giá đến nhà cung cấp đó, và bước kiểm tra trích dẫn của giám khảo sẽ tải các trang mà đầu ra trích dẫn; hoặc webhook, gửi ID, kết quả đánh giá và tên quy tắc — không bao giờ gửi văn bản — đến địa chỉ bạn đặt.
Yêu cầu Node.js 22.13 trở lên. Kiểm tra bằng node --version.

Cơ sở dữ liệu demo, được ghi lại bởi scripts/demo-media.mts; mã nguồn nằm tại demo.mp4. Ảnh tĩnh: dashboard-overview.png.
Xem một lỗi ngay trên màn hình trong 60 giây
Không cần kết nối agent hay cấu hình — chỉ một lệnh:
npx @iris-eval/mcp-server --demo
Lệnh này tạo cơ sở dữ liệu demo — năm agent nhỏ, hai tuần chạy thử, mọi kết quả đánh giá đều do chính bộ máy tạo ra — rồi mở bảng điều khiển tại http://localhost:6920 (trình duyệt của bạn sẽ tự mở trong lần chạy đầu tiên). Bảng điều khiển mở ở mục Failures: những gì đã thất bại, xếp từ nghiêm trọng nhất và mới nhất trước, mỗi thẻ nêu tên quy tắc cùng bằng chứng. Đáng để nhấp xem: một vụ rò rỉ PII bị quy tắc an toàn phát hiện, một chỉ thị ẩn trong bài đăng diễn đàn mà trình tóm tắt đã làm theo, một con số không hề có trong tài liệu nguồn, hai lượt chạy trên cùng mười hai câu hỏi được so sánh bằng khoảng tin cậy (Runs), một quy tắc tùy chỉnh đã triển khai và một quy tắc đang tạm dừng cùng các dòng kiểm toán của chúng, và điểm số từ giám khảo LLM bị đánh trượt kèm lý do.
Dữ liệu demo nằm trong cơ sở dữ liệu riêng (demo.db trong thư mục chính của Iris — ~/.iris trên macOS/Linux, %USERPROFILE%\.iris trên Windows) và không bao giờ trộn lẫn với trace thật của bạn. Xóa toàn bộ dữ liệu bằng một lệnh:
npx @iris-eval/mcp-server --demo-clear
Kết nối agent của bạn
Trước tiên, xác nhận bản cài đặt hoạt động trên máy này — lệnh chạy ngoại tuyến và không mở bất kỳ dữ liệu nào của bạn:
npx @iris-eval/mcp-server --self-test # exit 0 = healthy
Sau đó thêm Iris vào MCP client của bạn. Một lệnh sẽ ghi vào tệp cấu hình riêng của client, giữ nguyên mọi server khác trong đó và ghim phiên bản bạn vừa chạy:
npx -y @iris-eval/mcp-server install claude-code
Các client: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list hiển thị những client được tìm thấy trên máy này, phiên bản Iris mà mỗi client chạy và tệp mà client đọc; install <client> --uninstall gỡ Iris khỏi client. Mọi client dùng chung một cơ sở dữ liệu, vì vậy sau khi nâng cấp, hãy chuyển tất cả cùng lúc bằng install --upgrade (Cập nhật). Khởi động lại client để tải cấu hình.
Claude Desktop: chỉ một cú nhấp. Mỗi bản phát hành từ 0.20.0 trở đi đều đính kèm iris-eval.mcpb, một MCP Bundle: tải bản mới nhất, mở tệp, rồi Claude Desktop sẽ hiện hộp thoại cài đặt. Không mục nào trong đó là bắt buộc — khóa Anthropic hoặc OpenAI cho giám khảo LLM là tùy chọn, còn bảng điều khiển là một công tắc mặc định tắt. Bundle chứa gói npm và các phần phụ thuộc, nên không cần cài thêm gì: Claude Desktop chạy Iris bằng Node đi kèm nếu phiên bản Node đó là 22.13 trở lên (Claude Desktop 1.1.6679 đi kèm Node 24.13), và Iris lưu trace bằng SQLite tích hợp sẵn của Node, trong cùng ~/.iris mà mọi kiểu cài đặt khác sử dụng. Ghi chú phát hành hướng dẫn cách xác minh chữ ký và chứng thực bản dựng.
Iris chạy được trong mọi MCP client, và mỗi client được liệt kê đều có một dòng cho biết cách kiểm tra. Được xác minh trong mọi lần chạy CI: Claude Code, Gemini CLI — client thật khởi chạy Iris từ cấu hình do trình cài đặt ghi và báo đã kết nối (claude mcp list, gemini mcp list), trên Linux, macOS và Windows; các hook của plugin ghi nhận Claude Code cũng được chạy qua những script thật. Được cấu hình theo tài liệu MCP riêng của từng client — trình cài đặt ghi vào tệp mà mỗi client hướng dẫn, tại đường dẫn được tài liệu chỉ định và theo đúng định dạng riêng (một khối mcpServers, servers của VS Code, context_servers của Zed, TOML của Codex), đồng thời giữ nguyên chú thích và mọi server khác; các bài kiểm thử đơn vị đối chiếu từng đường dẫn và từng bộ ghi định dạng với tài liệu đó: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Mỗi dòng kèm nguồn và ngày tài liệu được đọc: https://iris-eval.com/clients. Nếu muốn tự làm, chỉ cần một khối, có cả bảng điều khiển:
{
"mcpServers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
}
}
}
Khi kết nối, client sẽ liệt kê mười hai công cụ của Iris; bảng điều khiển chạy tại http://localhost:6920. Giờ hãy gửi nội dung này cho agent:
Ghi tác vụ vừa rồi vào Iris và đánh giá kết quả.
Trace sẽ xuất hiện trên bảng điều khiển cùng điểm số. Muốn MCP server chạy không giao diện? Bỏ --dashboard khỏi các đối số — bạn có thể mở cùng bảng điều khiển bất cứ lúc nào bằng npx @iris-eval/mcp-server --dashboard.
Một điều nên biết trước: MCP tool được gọi khi model quyết định gọi chúng. Iris không chặn agent của bạn, nên trace chỉ được ghi khi agent yêu cầu Iris ghi — hoặc vì bạn bảo agent làm vậy, hoặc vì mã của bạn gọi trực tiếp các tool. Hãy yêu cầu agent “ghi việc này vào Iris và đánh giá”, và agent sẽ làm. Nếu muốn ghi nhận mà không phụ thuộc vào việc model có chọn gọi hay không, POST /api/v1/traces thực hiện chính xác điều đó — mã của bạn gửi trace qua HTTP thuần, không có model tham gia (xem docs/http-ingest.md). CLI và host hook trong lộ trình phát triển sẽ là các client gọn nhẹ dùng chung điểm cuối này.
Ghi nhận qua HTTP (không có model tham gia)
Điểm cuối ingest nằm trên cổng bảng điều khiển — mặc định là 6920, không phải cổng truyền tải MCP — và chỉ tồn tại khi bảng điều khiển đang chạy. Truyền --dashboard (hoặc đặt IRIS_DASHBOARD=true); chỉ riêng --transport http không khởi động nó, và yêu cầu gửi đến cổng truyền tải sẽ trả về 404. Khi bảng điều khiển đang chạy, bất cứ thứ gì có thể gửi yêu cầu HTTP đều có thể ghi trace — và tùy chọn chạy các lượt đánh giá xác định trong cùng yêu cầu. GET /api/v1/capabilities trên cùng cổng cho biết server có thể đánh giá những gì, mỗi quy tắc cần gì, trạng thái giám khảo cùng các bước bật tính năng đó, và các giới hạn — cùng một đối tượng mà tài nguyên MCP iris://capabilities cung cấp — để bên gọi HTTP có được thông tin nền như MCP client nhận được khi khởi tạo:
curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "support-bot",
"input": "What is the refund policy?",
"output": "Refunds are available within 30 days of purchase.",
"evaluate": true,
"eval_type": "safety"
}'
Trả về 201 cùng trace_id đã lưu và kết quả đánh giá (ở chế độ --demo, điểm cuối từ chối ghi bằng 403, nên dữ liệu demo không bao giờ trộn với dữ liệu của bạn). Điểm cuối chấp nhận cùng nội dung yêu cầu như tool log_trace và nằm sau cùng ngăn xếp middleware với phần còn lại của bảng điều khiển: mặc định chỉ bind vào loopback và có bảo vệ chống DNS rebinding, đồng thời hỗ trợ Bearer auth khi bạn thiết lập. Hai điều đơn giản cần biết: điểm cuối chấp nhận ghi không xác thực, trừ khi Iris được khởi chạy với --api-key (hoặc IRIS_API_KEY) — mặc định, bind loopback là thứ giới hạn truy cập trong máy của bạn, vì vậy hãy đặt khóa trước khi bind ra ngoài loopback; và dữ liệu được lưu nguyên văn — input và output được ghi vào iris.db chính xác như đã gửi, bao gồm mọi văn bản mà no_pii tiếp tục gắn cờ. Đặc tả đầy đủ, tham chiếu trường và ý nghĩa lỗi: docs/http-ingest.md.
Ghi lại mọi lượt Claude Code (tùy chọn)
/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval
Một plugin thứ hai, được cài riêng: các hook của plugin ghi lại prompt, lệnh gọi công cụ (kể cả những lệnh thất bại, cùng lỗi mà agent nhận được) và câu trả lời cuối cùng của mỗi lượt, được định danh bằng prompt; nhờ đó, các lệnh gọi của lượt bị gián đoạn và của sub-agent chạy nền cũng được gửi đến iris-eval ingest, theo cách tách rời, với các span quan trọng đã được che trong văn bản đánh giá được lưu — ghi nhận không phụ thuộc vào việc model có quyết định gọi tool hay không. Lượt kết thúc do lỗi API sẽ được lưu mà không đánh giá; nếu model cũng ghi lại lượt đó, cả hai trace đều được giữ lại và trace của plugin được đặt tên theo trace của model. Plugin không bao giờ in ra, chặn hay gửi bất cứ thứ gì đi đâu. Chỉ cài iris-eval không làm thay đổi vòng lặp lượt chạy của bạn. Giới hạn và cách gỡ bỏ: claude-plugin-capture/README.md.
Python
pip install iris-eval
from iris_eval import IrisClient
iris = IrisClient() # IRIS_URL, or the running dashboard's runtime.json
iris.evaluate_output("…", input="…", agent_name="support-bot")["verdict"] # {"state": "pass", "basis": "clean", "by": []}
Một client gọn nhẹ dùng HTTP API của server phiên bản 0.16.0 trở lên, được đánh phiên bản riêng — iris_eval.__version__ và trang PyPI hiển thị số phiên bản của nó, không phải của server: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), hỗ trợ đồng bộ và bất đồng bộ, câu trả lời có kiểu, thông báo từ chối do chính server tạo — cùng một pytest plugin: fixture iris và assert_iris(output, expect="pass") để khẳng định trạng thái của kết quả đánh giá. packages/python/README.md.
Ghi lại mọi lệnh gọi OpenAI và Anthropic
from iris_eval import wrap_openai
client = wrap_openai(OpenAI(), agent_name="support-bot") # every call: a GenAI span to POST /v1/traces, scored
import { wrapOpenAI } from '@iris-eval/sdk';
const openai = wrapOpenAI(new OpenAI(), { agentName: 'support-bot' });
Chỉ cần bọc client của nhà cung cấp một lần, mỗi lần gọi model sẽ trở thành một GenAI span OpenTelemetry được gửi đến cổng OTLP, lưu cùng đầu vào, đầu ra, mức sử dụng token và lệnh gọi công cụ, rồi được chấm điểm: ghi nhận không phụ thuộc vào việc model có gọi tool hay không. wrap_openai / wrap_anthropic trong client Python; wrapOpenAI, wrapAnthropic và irisMiddleware cho Vercel AI SDK trong @iris-eval/sdk. Cả hai hiện chưa được phát hành (bản iris-eval tiếp theo trên PyPI; @iris-eval/sdk được dựng từ mã nguồn cho đến khi có bản npm đầu tiên). Hỗ trợ stream, các hàm trợ giúp stream của SDK và lệnh gọi công cụ; client gốc không bị thay đổi, và Iris ngừng hoạt động cũng không làm gián đoạn lệnh gọi — packages/sdk/README.md, packages/python/README.md.
Chấm điểm mọi lượt chạy LangChain và LangGraph
from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})
Mỗi lượt chạy cấp cao nhất trở thành một trace (lượt chạy, các lần gọi model, các lần gọi công cụ và các nút đồ thị dưới dạng GenAI span) cùng đầu vào, đầu ra, lệnh gọi công cụ, mức sử dụng token và kết quả đánh giá. Python chạy trong client (pip install iris-eval, phiên bản 0.2.0 trở lên), JavaScript dưới dạng @iris-eval/langchain (nằm trong repository này, chưa phát hành lên npm). Cả hai đều được chứng minh trong CI bằng một ứng dụng LangGraph thật với model được lập trình sẵn; tính năng xuất OpenTelemetry của chính LangSmith cũng được chứng minh theo cách tương tự — docs/otel-recipes.md.
Cổng kiểm tra CI, không cần server
npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any
any làm job thất bại với mọi kết quả không phải pass: cả trường hợp thất bại lẫn trường hợp chưa được kiểm tra. Thay vào đó, hãy chỉ định một cơ sở đánh giá (--fail-on detector_veto) để chỉ thất bại khi cơ sở đó không đạt.
Hoặc dùng GitHub Action (0.16.0), làm job thất bại theo các kết quả bạn chỉ định, ghi biên nhận vào phần tóm tắt của job và đăng thành một bình luận trên pull request, được cập nhật ngay tại chỗ: uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 với traces: traces.ndjson — docs/ci-gate.md.
Cánh cửa thứ tư (0.15.0): POST /v1/traces trên cổng dashboard nhận dữ liệu OTLP/HTTP JSON hoặc protobuf mà phần instrumentation OpenTelemetry của bạn đã phát ra (exporter của Python SDK chỉ hỗ trợ protobuf, nên đây cũng là cánh cửa dành cho Python), và mỗi trace OTLP trở thành một trace Iris cùng các span của nó — docs/otel-integration.md; mỗi framework có một công thức riêng (Pydantic AI, Google ADK, LangGraph qua LangSmith, CrewAI, OpenAI Agents SDK cho Python và JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK và Mastra), mỗi công thức đều được kiểm chứng bằng fixture, tại docs/otel-recipes.md. ingest đọc một trace JSON (hoặc NDJSON, mỗi dòng một trace) từ stdin hoặc tệp, lưu trace, đánh giá theo đúng các quy tắc mà evaluate_output chạy, in một dòng JSON cho mỗi trace kèm kết luận và căn cứ, rồi thoát với mã 1 khi kết luận khớp với --fail-on. --dataset <id|label> giới hạn cổng kiểm tra đó ở các khóa case trong một dataset (POST /api/v1/datasets đưa các khóa case của một lần chạy vào dataset), để job chỉ thất bại với những case bạn đã chọn. Công thức đầy đủ, mã thoát và tám căn cứ được trình bày tại docs/ci-gate.md.
Viết quy tắc bằng mã
eval.plugins trong config.json tải các quy tắc bạn viết — một ES module có default export là { name, kind, mechanism, version, needs, evaluate(ctx) } — được ghim bằng sha256 của tệp, vì vậy nếu tệp đã thay đổi kể từ lúc bạn ghim, chương trình sẽ từ chối khởi động thay vì chạy. Plugin đã tải sẽ hoạt động như quy tắc tích hợp sẵn và xuất hiện trên list_rules trong mục plugins. Thỏa thuận, cách tính hash và những gì plugin có thể trả về: docs/plugins.md.
Dùng engine trong tiến trình của riêng bạn
Có thể import engine đánh giá — không cần server, cơ sở dữ liệu hay model:
import { EvalEngine, defaultConfig } from '@iris-eval/mcp-server/engine';
const engine = new EvalEngine(defaultConfig.eval.defaultThreshold, defaultConfig.eval.ruleThresholds, defaultConfig.eval);
const result = await engine.evaluateAll({ output: answer, input: prompt, toolCalls, costUsd });
result.verdict.state; // 'pass' | 'fail' | 'unknown', with result.verdict.basis and result.interpretations
Cùng engine, cùng quy tắc và cùng composer mà server chạy; builtInRules(), createCustomRule(), compose() và các trình đọc độ chính xác đã công bố cũng được export cùng với nó.
Client có kiểu dữ liệu cho HTTP route
import { createClient } from '@iris-eval/mcp-server/client';
const iris = createClient({ baseUrl: 'http://127.0.0.1:6920', apiKey: process.env.IRIS_API_KEY });
const { trace_id, evaluation } = await iris.logTrace({ agent_name: 'support-bot', input, output, tool_calls, evaluate: true });
evaluation?.verdict?.state; // the same object evaluate_output returns
Một body dùng cho mọi cổng: đây là body mà log_trace và iris-eval ingest chấp nhận. Khi từ chối, hệ thống ném IrisClientError kèm câu thông báo và status của chính server. Cả hai subpath đều được kiểm tra từ tarball đã đóng gói trong mỗi lần build.
Xác minh bản cài đặt
npx @iris-eval/mcp-server --self-test # offline diagnostic; exit 0 = healthy, 1 = a check failed
npx @iris-eval/mcp-server --version # prints the bare version, e.g. 1.2.3
--self-test trước tiên tạo thư mục Iris home nếu chưa có và kiểm tra xem có thể ghi vào đó không (thoát với mã 1, nêu đường dẫn nếu không thể), cho biết vị trí search index của cơ sở dữ liệu (đầy đủ, số trace mà tiến trình nền đã lập chỉ mục cho đến nay, hoặc không có FTS5 trên SQLite này), đọc schema của cơ sở dữ liệu (thoát với mã 1 và hướng dẫn khắc phục nếu phiên bản này hoặc MCP client được ghim ở bản phát hành cũ hơn không thể mở cơ sở dữ liệu), rồi chạy các bước kiểm tra — vòng lặp lưu trữ, SSN được cài sẵn và injection được cài sẵn bị các quy tắc an toàn phát hiện, khởi động dashboard, bộ bảo vệ DNS rebinding — trong một thư mục home tạm biệt lập. Cơ sở dữ liệu thật của bạn chỉ được đọc, không bao giờ bị thay đổi. Mọi thứ Iris ghi đều nằm trong một thư mục, Iris home của bạn: mặc định là ~/.iris (%USERPROFILE%\.iris trên Windows), hoặc vị trí mà IRIS_HOME trỏ đến. Đây là nơi lưu iris.db, config.json, custom-rules.json, audit.log, preferences.json và các tệp demo; trỏ IRIS_HOME đến một thư mục tạm để dùng thử Iris mà không động đến dữ liệu thật.
Thiết lập theo công cụ
| Client | Trạng thái | Ý nghĩa | Đọc |
|---|---|---|---|
| Claude Code | đã xác minh | một bài kiểm tra chạy client thật trong mỗi lần CI | 2026-09-25 |
| Claude Desktop | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Cursor | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Devin Desktop (Windsurf) | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Continue | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| VS Code | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Cline | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Zed | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| OpenAI Codex CLI | được khai báo | cấu hình theo tài liệu MCP của chính client; đường dẫn và định dạng của trình cài đặt được kiểm thử đơn vị | 2026-09-25 |
| Gemini CLI | đã xác minh | một bài kiểm tra chạy client thật trong mỗi lần CI | 2026-09-25 |
Mỗi hàng đều nêu rõ nội dung đã kiểm tra: iris-eval.com/clients. Không client nào được gọi là được hỗ trợ nếu không có một hàng.
npx -y @iris-eval/mcp-server install <client> ghi tất cả những mục này thay bạn. Nếu làm thủ công, theo từng client:
Claude Desktop
Chỉnh sửa tệp cấu hình MCP:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Thêm cấu hình JSON ở trên, rồi khởi động lại Claude Desktop.
Claude Code
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
Sau đó khởi động lại phiên (/clear hoặc chạy lại) để tải các công cụ.
Lưu ý cho Windows: Không dùng wrapper
cmd /c— wrapper này gây lỗi phân tích đường dẫn. Lệnhnpxhoạt động trực tiếp.
Cursor
Thêm cấu hình JSON ở trên vào ~/.cursor/mcp.json (mọi dự án) hoặc .cursor/mcp.json trong một workspace, với "type": "stdio" trong mục iris-eval — tài liệu của Cursor đánh dấu mục này là bắt buộc.
Devin Desktop (Windsurf)
Thêm cấu hình JSON ở trên vào mcp_config.json: ~/.config/devin/mcp_config.json trên macOS và Linux, %APPDATA%\devin\mcp_config.json trên Windows.
Continue
Lưu cấu hình JSON ở trên thành tệp riêng trong thư mục mcpServers của Continue: ~/.continue/mcpServers/iris-eval.json (mọi workspace) hoặc .continue/mcpServers/iris-eval.json trong một workspace.
VS Code (MCP tích hợp sẵn)
Thêm vào .vscode/mcp.json trong workspace của bạn (lưu ý: VS Code dùng servers, không phải mcpServers):
{
"servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"]
}
}
}
Cline
Mở bảng MCP Servers của Cline → Configure MCP Servers, rồi thêm cấu hình JSON mcpServers ở trên vào cline_mcp_settings.json (~/.cline/data/settings/cline_mcp_settings.json, được Cline dùng chung trong VS Code, JetBrains và CLI).
Zed
Thêm vào settings.json của Zed:
{
"context_servers": {
"iris-eval": {
"command": "npx",
"args": ["-y", "@iris-eval/mcp-server"],
"env": {}
}
}
}
OpenAI Codex CLI
Thêm vào ~/.codex/config.toml:
[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]
Gemini CLI
Thêm cấu hình JSON mcpServers ở trên vào ~/.gemini/settings.json. Gemini CLI chỉ kết nối với MCP server trong các thư mục mà nó tin cậy: nếu gemini mcp list hiển thị iris-eval là Disabled, hãy chạy /permissions trong thư mục đó.
Các client MCP khác
Iris là MCP server stdio tiêu chuẩn — chỉ cần một lệnh npx @iris-eval/mcp-server, không cần SDK hay thay đổi mã. Nếu client của bạn hỗ trợ MCP, client đó hỗ trợ Iris. Định dạng cấu hình của client có thể thay đổi; khi không chắc, hãy xem tài liệu MCP của client và trỏ client đến lệnh đó.
Các phương thức cài đặt khác
# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-eval --dashboard
# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint).
# The image binds 0.0.0.0 inside the container, so a key is required (see Production).
# The volume is the Iris home: the database, deployed rules and audit log persist in it.
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
-e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server
Mẹo: Cài đặt toàn cục (
npm install -g) lưu trace lâu dài tại~/.iris/iris.db. Vớinpx, trace vẫn được lưu ở cùng vị trí, nhưng quá trình khởi động chậm hơn do phải phân giải package.
Container image và các thư mục MCP có liệt kê Iris:
Những gì bạn nhận được
| Ghi nhật ký trace | Cây span phân cấp với độ trễ theo từng lần gọi công cụ, mức sử dụng token và chi phí tính bằng USD. Lưu trong SQLite, có thể truy vấn tức thì. |
| Đánh giá đầu ra | 28 quy tắc tích hợp sẵn thuộc 4 nhóm: tính đầy đủ, mức độ liên quan, an toàn, chi phí. Phát hiện PII (21 mẫu: SSN, thẻ tín dụng, số điện thoại, email, IBAN, DOB, MRN, IP, API key, hộ chiếu, cùng token AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean, thông tin xác thực bên trong URL, phép gán có tên bí mật, khối khóa riêng PEM và cụm từ seed; ngày sinh, số hồ sơ bệnh án, hộ chiếu và cụm từ seed chỉ kích hoạt khi nằm cạnh nhãn tương ứng, theo thiết kế), prompt injection (38 mẫu, gồm cụm từ và cấu trúc), phát hiện đầu ra giả, phát hiện ảo giác (25 tín hiệu bịa đặt/mâu thuẫn dựa trên ngữ cảnh — truyền input để đối chiếu chúng với tài liệu nguồn của agent), và sáu quy tắc quỹ đạo đọc những gì agent ĐÃ LÀM: một lần gọi công cụ thất bại nhưng không được thừa nhận, một lần gọi bị lặp lại (theo lần gọi, theo chuỗi lặp lại hoặc theo mục tiêu khi bạn gửi tools), một lần gọi có đối số bị JSON Schema của chính công cụ từ chối nhưng agent không thử lại, một tệp, thư mục hoặc URL được câu trả lời trích dẫn nhưng không xuất hiện trong bất kỳ nội dung nào agent đã đọc, một chỉ dẫn xuất hiện bên trong TOOL RESULT rồi được một lần gọi sau đó làm theo, và một tác vụ cần nhiều lần gọi công cụ hơn ngân sách bước của bạn. Hai quy tắc khác so sánh một lần chạy với các lần chạy trước đó của cùng agent cho cùng case, không cần ai viết kỳ vọng: một hành động mà không lần chạy trước nào thực hiện, và một bước mà mọi lần chạy trước đều thực hiện nhưng lần này thì không. Quỹ đạo có thể được truyền dưới dạng tool_calls hoặc dưới dạng span TOOL của OpenTelemetry. Thêm quy tắc tùy chỉnh bằng schema Zod. |
| LLM-as-Judge | Chấm điểm ngữ nghĩa tùy chọn qua Anthropic hoặc OpenAI — dùng API key của riêng bạn. Bảy mẫu. Khi đặt IRIS_RELEVANCE_JUDGE_MODEL, answers_the_ask gọi judge relevance và đánh trượt câu trả lời lạc đề; nếu không, quy tắc đọc yêu cầu theo từ vựng và đưa ra khuyến nghị. Giới hạn chi phí cứng cho mỗi lần đánh giá (IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL, mặc định $0.25), giá cho mỗi lần đánh giá được công bố trong kết quả. |
| Hiển thị chi phí | Tổng hợp chi phí của mọi agent trong bất kỳ khoảng thời gian nào. Đặt ngưỡng ngân sách. Nhận cảnh báo khi agent chi tiêu vượt mức. Trace gửi số lượng token và model nhưng không gửi chi phí (phần lớn trace OpenTelemetry và framework) sẽ được tính theo giá niêm yết của model và được đánh dấu là ước tính ở mọi nơi hiển thị; pricing.models trong config.json định giá các model không có trong bảng tích hợp sẵn — docs/cost.md. |
| Web Dashboard | Giao diện tối theo thời gian thực, hiển thị lỗi trước, sắp xếp từ tệ nhất đến mới nhất — trực quan hóa trace với tìm kiếm toàn văn trên nội dung của mọi trace, kết quả đánh giá, phân tích chi phí và bảng lệnh (⌘K) tìm kiếm các quy tắc, trace và đánh giá của riêng bạn. |
| Ưu tiên chạy cục bộ | Mọi thứ nằm trong SQLite trên ổ đĩa của bạn. Server tự lưu trữ không cần tài khoản hay đăng ký và không gửi telemetry. Chỉ có lưu lượng HTTP đi ra khi bạn chủ động bật: khóa LLM-judge của riêng bạn, tải trích dẫn, exporter OTel do bạn cấu hình hoặc webhook bạn thiết lập. |
Hướng phát triển tiếp theo: bản đồ năng lực — mọi câu hỏi Iris có thể được hỏi về mọi chủ đề, cùng những gì Iris có và còn thiếu — và ba lộ trình.
Được đo lường, không chỉ tuyên bố
Mỗi quy tắc tích hợp sẵn đều có độ chính xác, độ thu hồi và F1 được công bố cùng khoảng tin cậy 95%, đo trên một tập dữ liệu có nhãn nằm trong kho lưu trữ này (proof/corpus/) và có thể tạo lại bằng một lệnh — npm run proof — ngoại tuyến, không cần khóa và không có mô hình tham gia. Các con số đó thuộc hai loại khác nhau và trang này không bao giờ cộng chúng lại: một số quy tắc được đo dựa trên nhãn do mô hình đưa ra sau khi đọc chính lỗi, qua đó đo khả năng phát hiện; các quy tắc còn lại được kiểm tra theo định nghĩa đã được ghi lại của chính chúng, áp dụng độc lập, cho thấy mã triển khai đúng công thức nhưng không nói gì về việc công thức đó có phát hiện được lỗi hay không. proof/RESULTS.md và trang bằng chứng đánh dấu từng quy tắc. CI chạy lại phép đo trên mỗi pull request và thất bại nếu các con số đã commit khác với kết quả do mã tạo ra, vì vậy quy tắc không thể thay đổi mà không làm các con số của nó thay đổi theo. Các con số có tại iris-eval.com/proof và trong proof/RESULTS.md; cách tạo tập dữ liệu, những điều tập dữ liệu không đại diện và cách đọc khoảng tin cậy được trình bày trong docs/proof.md. Tập dữ liệu là dữ liệu tổng hợp và được gán nhãn bằng mô hình — việc gán nhãn mù bởi con người vẫn đang chờ thực hiện, và trang này nói rõ điều đó; node proof/blind-sample.mjs lấy mẫu có thể tái lập để giải quyết vấn đề này.
Công cụ MCP
Iris đăng ký mười hai công cụ mà mọi tác nhân tương thích với MCP đều có thể gọi — theo dõi và vòng đời quy tắc, so sánh giữa các lần chạy, LLM-as-judge và xác minh trích dẫn ngữ nghĩa:
log_trace— Ghi nhật ký một lần thực thi của tác nhân cùng các span, lệnh gọi công cụ, mức sử dụng token và chi phí; truyềnevaluate: trueđể chấm điểm trong cùng lệnh gọievaluate_output— Chấm điểm chất lượng đầu ra theo các quy tắc về tính đầy đủ, mức độ liên quan, an toàn và chi phí (heuristic, xác định, miễn phí)get_traces— Truy vấn các trace đã lưu với khả năng lọc, phân trang và hỗ trợ khoảng thời gian, đồng thời tìm lần chạy mà tác nhân đã nói điều gì đó bằngq: tìm kiếm toàn văn trên đầu vào, đầu ra, giá trị lệnh gọi công cụ và siêu dữ liệu, có xếp hạng và đánh dấu các từ khớplist_rules— Liệt kê các quy tắc đánh giá tùy chỉnh đã triển khai (chỉ đọc)deploy_rule— Đăng ký quy tắc đánh giá tùy chỉnh mới để quy tắc được kích hoạt trên mọievaluate_outputthuộc danh mục đódelete_rule— Xóa quy tắc tùy chỉnh đã triển khai (có tính phá hủy, idempotent)delete_trace— Xóa một trace đã lưu theo ID (có tính phá hủy, giới hạn theo tenant)evaluate_with_llm_judge— Đánh giá ngữ nghĩa qua LLM (Anthropic hoặc OpenAI). Bảy mẫu: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance. Giới hạn chi phí, công khai giá theo từng lần đánh giá. Tự cung cấp khóa API (IRIS_ANTHROPIC_API_KEYhoặcIRIS_OPENAI_API_KEY) — Iris không proxy hay chuyển tiếp các lệnh gọi LLM.verify_citations— Trích xuất trích dẫn từ đầu ra (đánh số, tác giả-năm, URL, DOI), truy xuất nguồn bằng bộ phân giải có bảo vệ SSRF và danh sách cho phép theo miền, rồi dùng LLM judge để kiểm tra xem từng nguồn có thực sự hỗ trợ nhận định được trích dẫn hay không. HTTP gửi đi chỉ khi bật tùy chọn. Yêu cầu BYOK giống nhưevaluate_with_llm_judge.compare_runs— Thay đổi có khiến tác nhân hoạt động kém hơn không? So sánh hai lần chạy đánh giá đã lưu: kiểm định chính xác theo cặp khi các lần chạy dùng chung khóa trường hợp, khoảng tin cậy của chênh lệch trong trường hợp còn lại, kết quả trung thực “không thể kết luận” kèm số trường hợp cần có, hoặc “tương đương trong phạm vi sai số”. Mỗi quy tắc có kiểm định một phía riêng, được hiệu chỉnh đồng thời (Benjamini–Hochberg) để hai mươi quy tắc không thể tạo ra hồi quy giảcompare_traces— Tác nhân trả lời cùng một câu hỏi đáng tin cậy đến mức nào? Tỷ lệ đạt theo từng trường hợp kèm khoảng tin cậy, ưu tiên các trường hợp không ổn định, và tỷ lệ tổng thể có tính đến số lần lặpevaluate_runs— Chấm điểm lại mọi trace trong một lần chạy theo các quy tắc hiện tại vào một lần chạy mới, để thay đổi quy tắc không bao giờ bị hiểu nhầm là thay đổi của tác nhân
Bật LLM judge (tùy chọn; các quy tắc xác định không bao giờ cần đến nó)
- Lấy khóa API từ Anthropic hoặc OpenAI.
- Đặt khóa trong môi trường của tiến trình chạy Iris, không chỉ trong shell của bạn. Claude Code, Claude Desktop, Cursor và hầu hết ứng dụng khách MCP: khối "env" của mục iris-eval trong cấu hình MCP — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY nếu dùng khóa OpenAI). Docker: thêm -e IRIS_ANTHROPIC_API_KEY=... vào lệnh chạy. HTTP hoặc CI: export biến này trước khi khởi động iris-eval.
- Khởi động lại phiên MCP. Một tiến trình đang chạy sẽ không thấy biến được đặt sau khi tiến trình khởi động.
- Xác nhận từ bên trong ứng dụng khách của bạn: đọc iris://capabilities — judge.enabled phải là true tại đó. Khóa được export trong shell sẽ không được truyền cho tiến trình mà ứng dụng khách khởi chạy, trừ khi cấu hình của ứng dụng liệt kê khóa đó. Trên máy,
npx @iris-eval/mcp-server --self-testin dòng judge cho shell đó, còn GET /api/v1/health báo cáo judge.enabled trên dashboard đang chạy. - Giới hạn chi tiêu: mỗi lệnh gọi bị giới hạn bởi IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (mặc định 0.25 USD) và bị từ chối trước khi phát sinh chi phí nếu trường hợp xấu nhất vượt quá giới hạn. Mọi lệnh gọi judge mà Iris thực hiện bằng khóa của bạn đều dùng chung một ngân sách hằng ngày, IRIS_LLM_JUDGE_DAILY_BUDGET_USD (mặc định 1 USD mỗi ngày UTC); khi vượt ngân sách, sẽ không có lệnh gọi nào được thực hiện cho đến nửa đêm UTC. Iris gọi trực tiếp nhà cung cấp bằng khóa của bạn và không bao giờ proxy khóa đó.
- Tùy chọn: đặt IRIS_RELEVANCE_JUDGE_MODEL thành ID mô hình có giá (ví dụ claude-haiku-4-5) để answers_the_ask yêu cầu judge đánh giá xem mỗi câu trả lời có đáp ứng yêu cầu hay không và đánh trượt câu trả lời lạc đề. Mỗi lần đánh giá có đầu vào sẽ tạo một lệnh gọi judge, dùng khóa của bạn và nằm trong giới hạn chi phí nêu trên; chỉ có khóa thôi sẽ không tự bật tính năng này. Mỗi lệnh gọi gửi đầu vào và đầu ra đó đến nhà cung cấp mô hình, sau khi thay thế các cờ no_pii của dữ liệu cá nhân và thông tin xác thực (IRIS_RELEVANCE_JUDGE_REDACT=off sẽ gửi nguyên trạng). Lệnh gọi dùng ngân sách hằng ngày đó và mỗi yêu cầu có tối đa IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST lệnh gọi (mặc định 20); khi vượt một trong hai giới hạn, answers_the_ask sẽ đọc yêu cầu theo từ vựng và giải thích lý do.
Khi đã cấu hình IRIS_OTEL_ENDPOINT, các lệnh gọi log_trace cũng thực hiện xuất OTLP/HTTP JSON theo cơ chế best-effort đến bất kỳ bộ thu thập OpenTelemetry nào (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, v.v.). Xem docs/otel-integration.md.
Cách quyết định passed
evaluate_output trả về cả score lẫn cờ passed — chúng trả lời những câu hỏi khác nhau:
score(0..1) là trung bình có trọng số của các quy tắc đã chạy — một thước đo mức chất lượng.passedlà kết luận có phát hành hay không, và điểm số không bao giờ được dùng để đưa ra kết luận này. Bộ tổng hợp đọc từng quy tắc theo loại nhận định mà quy tắc đưa ra: chính sách bạn cấu hình sẽ chặn; bộ phát hiện quan trọng có quyền phủ quyết; một phép kiểm tra quan trọng đã được yêu cầu nhưng không thể đưa ra kết quả sẽ khiến kết luận là unknown (passed: false) thay vì đạt; mọi bộ phát hiện còn lại được kết hợp thành một xác suất đầu ra không đạt, cân nhắc theo tỷ lệ tổn thất bạn nêu trongeval.falsePassCost(mặc định là 1, nên ngưỡng là 0.5).verdict.basisnêu tên lớp đưa ra quyết định vàverdict.bynêu các quy tắc;verdict.alsoliệt kê mọi lớp phía sau cũng sẽ đưa ra quyết định;interpretations[]giải thích vì sao một quy tắc không đạt không đưa ra quyết định và cài đặt nào sẽ thay đổi điều đó, đồng thời nêu tên mọi câu hỏi chưa được đánh giá và đầu vào cần có để đánh giá câu hỏi đó.
Các vi phạm an toàn thực sự sẽ khiến đánh giá thất bại ngay. Theo mặc định, no_pii, no_injection_patterns và no_blocklist_words là quy tắc quan trọng: nếu một quy tắc không đạt, kết quả đánh giá sẽ là passed: false bất kể các quy tắc khác đạt điểm cao đến đâu, và phản hồi sẽ nêu tên các quy tắc gây ra kết quả đó trong critical_failures. Không thể lấy điểm trung bình để xóa bỏ việc làm lộ SSN. Những quy tắc tích hợp nào là quan trọng được quyết định bởi cài đặt triển khai (eval.criticalRules / eval.nonCriticalRules), và quy tắc phát hiện nào chỉ báo cáo cũng vậy (eval.advisoryRules); kết quả của mỗi quy tắc đều có cờ critical hiệu lực và criticalSource, còn list_rules báo cáo danh sách quy tắc mà máy chủ này áp dụng. Các quy tắc tùy chỉnh được triển khai bằng severity: "high" hoặc "critical" cũng khiến đánh giá thất bại theo cách tương tự; mức độ nghiêm trọng low/medium chỉ ảnh hưởng đến điểm số. Cần lưu ý một ranh giới, được nêu giống nhau trên mọi giao diện: quy tắc quan trọng bị bỏ qua (thiếu ngữ cảnh, định nghĩa bị lỗi hoặc regex bị dừng khi hết ngân sách sandbox) chưa đánh giá đầu ra và không phủ quyết — mọi quy tắc như vậy đều được nêu trong critical_skipped. Một cổng bắt buộc phải đóng khi không chắc chắn sẽ coi critical_skipped không rỗng là unknown, không phải đạt, và có thể xử lý mọi trường hợp bỏ qua budgetExceeded trong rule_results theo cách tương tự.
Đối với cổng CI: nếu bạn bỏ qua eval_type, mọi nhóm quy tắc đều chạy — tính đầy đủ, mức độ liên quan, an toàn, chi phí và mọi quy tắc tùy chỉnh — và phản hồi cho biết eval_type: "all" cùng với note xác nhận nhóm mặc định đã chạy, kèm bản đồ categories theo từng nhóm. Mỗi hàng có state: kết luận dành cho các quy tắc thuộc nhóm đó, để một hàng không bao giờ báo đạt khi các quy tắc khiến toàn bộ đánh giá không đạt đã bị bỏ qua. Nhóm không có gì để đánh giá (chi phí khi không có cost_usd, mức độ liên quan khi không có input) sẽ báo cáo state: "unknown" và passed: null tại đó — không được đánh giá, không phải không đạt — và không bao giờ được tính vào kết luận. Phản hồi luôn phản ánh lại eval_type đã chạy để cổng của bạn có thể xác minh phạm vi bao phủ; dùng passed làm khóa cho kết luận và chỉ định tên nhóm khi bạn muốn chạy phạm vi hẹp hơn.
Tạo quy tắc tùy chỉnh
Có hai cách thêm quy tắc. Quy tắc nội tuyến đi kèm một lệnh gọi evaluate_output (custom_rules, tối đa 10 quy tắc mỗi lệnh gọi); chúng chạy cùng với nhóm eval_type bạn chọn, hoặc chạy riêng với eval_type: "custom". Quy tắc đã triển khai được đăng ký một lần bằng deploy_rule, lưu lại trong custom-rules.json dưới thư mục chính của Iris và chạy trên mọi evaluate_output trong tương lai thuộc evalType của chúng. Định nghĩa có cùng cấu trúc trong cả hai trường hợp:
| Trường | Bắt buộc | Ý nghĩa |
|---|---|---|
name | có | 1–80 ký tự; xuất hiện dưới dạng ruleName trong kết quả |
type | có | một trong các giá trị regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold |
config | có | các khóa cho loại đó: pattern (+ flags tùy chọn) cho hai loại regex · min_length / max_length (số ký tự) · keywords (+ threshold tùy chọn, 0–1, mặc định 1 = tất cả đều phải xuất hiện) cho hai loại từ khóa · {} cho json_schema · max_cost tính bằng USD cho cost_threshold |
weight | không | trọng số trong điểm số; mặc định là 1 |
deploy_rule bao bọc định nghĩa cùng với name, một description tùy chọn, evalType (completeness · relevance · safety · cost · custom) và severity. Mức độ nghiêm trọng cho biết ý nghĩa của một lần không đạt: low/medium chỉ làm giảm điểm số; high/critical khiến đánh giá thất bại ngay — passed: false, quy tắc được nêu tên trong critical_failures — bất kể điểm số có trọng số ra sao. Quy tắc bị bỏ qua (quy tắc cost_threshold không có cost_usd, hoặc regex bị dừng khi hết ngân sách sandbox 100 ms) chưa đánh giá đầu ra và thay vào đó được liệt kê trong critical_skipped. Triển khai một quy tắc quan trọng để cấm tên máy chủ nội bộ trong mọi nội dung tác nhân nói ra:
{
"name": "no_internal_hostnames",
"description": "Output must not mention internal hostnames.",
"evalType": "safety",
"severity": "critical",
"definition": {
"name": "no_internal_hostnames",
"type": "regex_no_match",
"config": { "pattern": "\\b[a-z0-9-]+\\.internal\\.example\\b", "flags": "i" }
}
}
Phản hồi là quy tắc đã được lưu — hãy giữ lại id cho delete_rule:
{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }
Từ evaluate_output tiếp theo với eval_type: "safety", một đầu ra nhắc đến db-primary.internal.example sẽ trở lại passed: false với critical_failures: ["no_internal_hostnames"] — mặc dù cả năm quy tắc an toàn tích hợp đều đạt và điểm có trọng số là 0.895. Các mẫu Regex phải vượt qua kiểm tra ReDoS khi triển khai và luôn chạy trong worker sandbox với thời hạn cứng 100 ms. list_rules cho biết những gì đang được triển khai; trình soạn quy tắc trên bảng điều khiển tạo cùng cấu trúc từ một lỗi bạn đã nhấp vào. Tài liệu tham khảo đầy đủ, cách tính điểm theo từng loại và ví dụ minh họa: docs/custom-rules.md.
Lược đồ công cụ và cấu hình đầy đủ: iris-eval.com
Tự lưu trữ và miễn phí
Iris chạy trên máy của bạn hoặc hạ tầng riêng. Phần lõi mã nguồn mở miễn phí và được cấp phép MIT, không giới hạn sử dụng và không cần tài khoản. Lưu trữ trên dịch vụ, lịch sử dùng chung cho nhóm và cảnh báo đang được cân nhắc, chưa được xây dựng; nếu những tính năng đó hữu ích với bạn, hãy cho chúng tôi biết tại hello@iris-eval.com.
Hai cam kết luôn được giữ vững: không tính năng nào hiện miễn phí sẽ bị chuyển sang hình thức trả phí, và không tuyên bố có chứng nhận tuân thủ trước khi thực sự đạt được chứng nhận đó.
Ví dụ
- Thiết lập Claude Desktop — cấu hình MCP cho chế độ stdio và HTTP
- TypeScript — ứng dụng khách MCP SDK — kết nối và gọi công cụ
- Truyền tải HTTP (TS + Python) — mã ứng dụng khách đầy đủ để tích hợp theo kiểu REST
- Một tác tử LangGraph, chấm điểm từng lượt chạy (Python) —
IrisCallbackHandlertrong các callback của đồ thị; CI chạy cùng đồ thị với một mô hình được lập trình sẵn - Một nhóm CrewAI qua OpenTelemetry (Python) — instrumentor OpenInference kết nối thẳng đến cổng OTLP của Iris, công thức CrewAI dưới dạng tập lệnh
- Một tác tử OpenAI Agents SDK qua OpenTelemetry (Python) và (JavaScript), cùng một tác tử LlamaIndex — mỗi công thức là tập lệnh mà CI chạy với một máy chủ Iris thực
Cộng đồng
- GitHub Issues — Báo lỗi và yêu cầu tính năng
- GitHub Discussions — Câu hỏi và ý tưởng
- Nhận trợ giúp — Nơi đặt câu hỏi, báo lỗi hoặc báo lỗ hổng bảo mật
- Hướng dẫn đóng góp — Cách đóng góp; AGENTS.md là cùng hướng dẫn đó dành cho tác tử lập trình
- Quản trị — Ai quyết định, cách một thay đổi được đưa vào và cách một bản phát hành được tạo cũng như xác minh
- HTTP Ingest — Ghi nhận trace xác định thông qua
POST /api/v1/traces - Bản đồ khả năng — Mọi câu hỏi có thể đặt cho Iris và những gì Iris còn thiếu
- Chính sách phiên bản — Mỗi số phiên bản cam kết điều gì và cần đáp ứng những gì trước phiên bản 1.0
Cấu hình & Bảo mật
Đối số CLI
| Cờ | Mặc định | Mô tả |
|---|---|---|
--transport | stdio | Loại truyền tải: stdio hoặc http |
--port | 3000 | Cổng truyền tải HTTP |
--db-path | ~/.iris/iris.db | Đường dẫn cơ sở dữ liệu SQLite |
--config | ~/.iris/config.json | Đường dẫn tệp cấu hình |
--api-key | — | Khóa API để xác thực HTTP (truyền tải và bảng điều khiển, bao gồm POST /api/v1/traces) |
--dashboard | false | Bật bảng điều khiển web. Đây cũng là cách duy nhất để điểm cuối ingest POST /api/v1/traces khởi chạy — điểm cuối này không bao giờ tự khởi chạy cùng với --transport http |
--dashboard-port | 6920 | Cổng bảng điều khiển |
--dashboard-host | 127.0.0.1 | Địa chỉ bind của bảng điều khiển. Mặc định là loopback — bảng điều khiển không có xác thực trừ khi đặt --api-key, vì vậy bind ra ngoài loopback sẽ để lộ toàn bộ lịch sử trace của bạn |
--demo | false | Tạo cơ sở dữ liệu demo (tách biệt với trace thực của bạn) và phục vụ bảng điều khiển bằng cơ sở dữ liệu đó |
--demo-clear | false | Xóa cơ sở dữ liệu demo rồi thoát |
--self-test | false | Chạy chẩn đoán cài đặt ngoại tuyến trong thư mục home tạm thời biệt lập, rồi thoát (0 = hoạt động bình thường, 1 = có kiểm tra thất bại). Lệnh này cũng đọc cơ sở dữ liệu đã cấu hình ở chế độ chỉ đọc và báo lỗi nếu phiên bản này hoặc một MCP client được ghim phiên bản không thể mở cơ sở dữ liệu |
--purge | false | Xóa mọi trace, span và đánh giá đã lưu khỏi cơ sở dữ liệu được cấu hình, thu gọn tệp và cắt ngắn nhật ký ghi trước để văn bản đã xóa không còn lưu lại trên đĩa, rồi thoát. Các quy tắc đã triển khai, nhật ký kiểm tra và tùy chọn vẫn được giữ lại. Không thể hoàn tác. Trước tiên hãy dừng mọi máy chủ Iris đang chạy — tệp được thu gọn ngay tại chỗ. Từ chối kết hợp với --demo, --demo-clear hoặc --self-test |
--version | — | In phiên bản thuần (ví dụ: 1.2.3) ra stdout rồi thoát với mã 0. Không đọc bất kỳ thứ gì trong thư mục home Iris của bạn |
Ba lệnh nhận đối số riêng và thoát: iris-eval ingest tải trace từ tệp hoặc stdin (Một cổng kiểm tra CI, không cần máy chủ), iris-eval export traces|evaluations --format csv|jsonl ghi dữ liệu đã lưu, được lọc như các danh sách trên bảng điều khiển, ra stdout hoặc --out (docs/api-reference.md), còn iris-eval install <client> ghi Iris vào cấu hình của MCP client — --uninstall gỡ Iris khỏi cấu hình, --list hiển thị các client tìm thấy trên máy này và phiên bản Iris mà từng client chạy, --upgrade chuyển mọi client đang chạy Iris sang phiên bản này (Kết nối tác tử của bạn, Cập nhật). Không lệnh nào khởi chạy máy chủ.
config.json được xác thực khi Iris khởi động. Nếu Iris không đọc một khóa — chẳng hạn như eval.critcalRules do gõ nhầm, một khóa của công cụ khác — hoặc giá trị có kiểu không đúng, quá trình khởi động sẽ bị từ chối kèm một câu nêu tên đầy đủ của khóa, khóa có khả năng được định dùng nhất hoặc kiểu dữ liệu được yêu cầu. Không có nội dung nào trong tệp bị âm thầm bỏ qua.
Biến môi trường
Mọi biến --help đều được ghi lại. Khi cả hai cùng được đặt, cờ CLI được ưu tiên hơn biến môi trường.
| Biến | Mô tả |
|---|---|
IRIS_TRANSPORT | Loại truyền tải (stdio hoặc http) |
IRIS_HOST | Địa chỉ liên kết của truyền tải HTTP (mặc định 127.0.0.1) |
IRIS_PORT | Cổng truyền tải HTTP (1-65535, mặc định 3000) |
IRIS_HOME | Thư mục chứa tất cả tệp theo từng người dùng: config.json, iris.db, custom-rules.json, audit.log, preferences.json (mặc định ~/.iris) |
IRIS_DB_PATH | Đường dẫn cơ sở dữ liệu SQLite (chỉ ghi đè IRIS_HOME đối với DB) |
IRIS_SQLITE_DRIVER | Trình điều khiển SQLite nào lưu cơ sở dữ liệu: native (better-sqlite3, mặc định) hoặc node (tích hợp sẵn trong Node node:sqlite, Node 22.13+). Nếu không đặt: dùng native; khi không tải được mô-đun native (hoặc đó là bản dựng sẽ gây lỗi nghiêm trọng trên Node này), Iris cảnh báo một lần rồi chuyển sang dùng bản tích hợp sẵn |
IRIS_SEARCH_BUDGET_MS | Thời gian tối đa một lần tìm kiếm trace (q) được phép đọc trước khi trả lời với các kết quả đã tìm thấy cho đến lúc đó và search.complete: false, tính bằng mili giây (50 đến 60000, mặc định 1000). Trong khi đọc, một lượt tìm kiếm sẽ chặn các yêu cầu khác, vì vậy đây cũng là thời gian chờ tối đa mà nó có thể khiến các yêu cầu đó phải chịu. Cũng là storage.searchBudgetMs trong config.json |
IRIS_SEARCH_INDEX | on (mặc định) hoặc off. off không lưu chỉ mục toàn văn của các trace: thao tác ghi chỉ lưu trace, không làm gì thêm; thao tác tìm kiếm trace (q) đọc trực tiếp các trace trong phạm vi IRIS_SEARCH_BUDGET_MS, theo thứ tự mới nhất trước, nên với kho dữ liệu lớn, kết quả có thể chỉ chứa một phần các kết quả khớp (search.complete: false). Tắt tùy chọn này sẽ xóa chỉ mục mà cơ sở dữ liệu đã lưu; bật lại sẽ tạo chỉ mục mới ở chế độ nền. Cũng là storage.searchIndex trong config.json |
IRIS_LOG_LEVEL | Cấp độ nhật ký: debug, info, warn, error |
IRIS_DASHBOARD | true/1/yes/on bật bảng điều khiển web; false/0/no/off tắt bảng điều khiển (cũng ghi đè dashboard.enabled trong config.json) |
IRIS_DASHBOARD_PORT | Cổng bảng điều khiển (1-65535, mặc định 6920) |
IRIS_WEBHOOK_URL | Nơi nhận webhook được kích hoạt khi có một moment — được gộp với notify.webhook trong config.json (docs/webhooks.md) |
IRIS_WEBHOOK_SECRET | Khóa ký webhook (bất kỳ chuỗi nào, hoặc whsec_ + base64); định dạng iris sẽ từ chối chạy nếu không có khóa |
IRIS_DASHBOARD_HOST | Địa chỉ liên kết của bảng điều khiển (mặc định 127.0.0.1) |
IRIS_API_KEY | Khóa API dùng để xác thực HTTP. Bắt buộc khi liên kết truyền tải HTTP hoặc bảng điều khiển với địa chỉ ngoài loopback (0.0.0.0, địa chỉ LAN, container): nếu không có khóa, máy chủ sẽ từ chối khởi động |
IRIS_API_KEY_FILE | Đường dẫn đến tệp có nội dung sau khi cắt khoảng trắng là khóa API — mẫu tệp bí mật được Docker và Kubernetes gắn vào, để khóa không bao giờ nằm trong khối biến môi trường. Đặt biến này hoặc IRIS_API_KEY, không đặt cả hai |
IRIS_ALLOW_UNAUTHENTICATED | Đặt thành 1 để chủ ý chạy với địa chỉ liên kết không phải loopback mà không có khóa (bỏ qua việc từ chối; khi đó mạng là ranh giới bảo vệ của bạn) |
IRIS_ALLOWED_ORIGINS | Danh sách cho phép origin, phân tách bằng dấu phẩy. Bảng điều khiển: các tiêu đề CORS (hỗ trợ ký tự đại diện, ví dụ http://localhost:*). Truyền tải HTTP: danh sách cho phép Origin khớp chính xác để bảo vệ khỏi DNS rebinding (bỏ qua ký tự đại diện; các origin loopback của chính máy chủ luôn được cho phép) |
IRIS_MAX_INPUT_ELEMENTS | Số phần tử mảng và khóa đối tượng tối đa mà một đầu vào có thể chứa trước khi được xác thực (số nguyên, mặc định 100000): áp dụng cho đối số của lệnh gọi công cụ trên mọi phương thức truyền tải và nội dung yêu cầu trên cổng bảng điều khiển (các nội dung JSON của API và POST /v1/traces, JSON hoặc protobuf). Lệnh gọi công cụ vượt giới hạn sẽ nhận kết quả lỗi; nội dung yêu cầu vượt giới hạn sẽ 413. Mặc định này đủ cho mọi đầu vào JSON hợp lệ đã đo, kể cả đầu vào chiếm trọn yêu cầu 1 MB. Nội dung protobuf trên POST /v1/traces có giới hạn riêng: một phần tử trên mỗi 5 byte của security.requestSizeLimit (209,716 ở mức 1 MB), hoặc theo cài đặt này nếu cao hơn, nên lô của exporter nằm trong giới hạn kích thước yêu cầu sẽ không bị từ chối vì có mật độ quá cao (nội dung exporter thực tế có mật độ cao nhất đã đo chứa một phần tử trên mỗi 7.5 byte); tăng requestSizeLimit cho các lô lớn hơn của collector cũng sẽ tăng giới hạn này. Cũng là security.maxInputElements trong config.json |
IRIS_MAX_TOOL_INPUT_ELEMENTS | Tên của IRIS_MAX_INPUT_ELEMENTS trước phiên bản 0.21.0, được đọc khi tên mới chưa được đặt (và security.maxToolInputElements trong config.json, tương tự) |
IRIS_NO_AUTO_LAUNCH | Đặt thành 1 để tắt tự động mở bảng điều khiển trong lần chạy đầu tiên |
IRIS_ANTHROPIC_API_KEY | Bắt buộc bởi evaluate_with_llm_judge + verify_citations với provider=anthropic |
IRIS_OPENAI_API_KEY | Bắt buộc bởi evaluate_with_llm_judge + verify_citations với provider=openai |
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL | Giới hạn chi phí cứng cho mỗi lần gọi LLM judge (mặc định 0.25). max_cost_usd có thể giảm giới hạn này cho một lần gọi, nhưng không thể tăng |
IRIS_RELEVANCE_JUDGE_MODEL | ID mô hình judge có tính phí (ví dụ claude-haiku-4-5). Khi được đặt cùng với khóa của nhà cung cấp tương ứng, answers_the_ask sẽ hỏi LLM judge này trong mọi lần đánh giá có đầu vào và dựa vào phán quyết về mức độ liên quan của nó — một lần gọi judge cho mỗi lần đánh giá, trong giới hạn chi phí ở trên và hai giới hạn bên dưới. Đầu vào và đầu ra của mỗi lần đánh giá như vậy sẽ được gửi đến nhà cung cấp mô hình đó (Anthropic hoặc OpenAI) bằng khóa của bạn, sau khi thay thế dữ liệu cá nhân và thông tin xác thực được đánh dấu bằng no_pii. Nếu không đặt (mặc định), answers_the_ask đọc yêu cầu theo từ vựng và đưa ra lời khuyên; không có dữ liệu nào được gửi đi (docs/llm-as-judge.md) |
IRIS_LLM_JUDGE_DAILY_BUDGET_USD | Tổng chi phí tối đa mà mọi lần gọi judge được phép tiêu tốn trong mỗi ngày UTC, cho mỗi tenant (mặc định 1): judge mức độ liên quan, evaluate_with_llm_judge và verify_citations dùng chung giới hạn này. Được lưu trong cơ sở dữ liệu nên khởi động lại không đặt lại giới hạn. Chỉ thực hiện một lần gọi nếu chi phí tối đa của nó nằm trong phần ngân sách còn lại; khi vượt giới hạn, answers_the_ask đọc yêu cầu theo từ vựng (judge.withheld: "daily_budget") và các công cụ judge trả lời IRIS_BUDGET_EXCEEDED (một trích dẫn, daily_budget_reached). 0 dừng mọi lần gọi |
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD | Tên của IRIS_LLM_JUDGE_DAILY_BUDGET_USD trước phiên bản 0.21.0, khi biến này chỉ giới hạn judge mức độ liên quan. Được đọc khi tên mới chưa được đặt; khi đó nó giới hạn mọi lần gọi judge và máy chủ thông báo điều này lúc khởi động |
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST | Số lần gọi judge mức độ liên quan tối đa mà một yêu cầu có thể thực hiện (mặc định 20): một lô OTLP hoặc lần chấm điểm lại evaluate_runs sẽ dùng judge cho 20 trace đầu tiên và đọc phần còn lại theo từ vựng, với judge.withheld: "request_cap" |
IRIS_RELEVANCE_JUDGE_REDACT | on (mặc định): mọi cờ no_pii (dữ liệu cá nhân và thông tin xác thực) trong span ở đầu vào và đầu ra đều được thay bằng dấu đánh dấu [REDACTED:<kind>#<n>] trước khi gửi đến judge mức độ liên quan. off gửi nguyên trạng |
IRIS_CITATION_ALLOW_FETCH | Đặt thành 1 để cho phép HTTP gửi đi trong verify_citations (mặc định tắt). Đối số công cụ có thể tắt tùy chọn này cho một lần gọi, nhưng không thể bật |
IRIS_CITATION_DOMAINS | Danh sách hostname cho phép, phân tách bằng dấu phẩy, dành cho verify_citations (khớp hậu tố). Đối số công cụ có thể thu hẹp danh sách, nhưng không thể thêm vào |
IRIS_CITATION_MAX_COST_USD_TOTAL | Mức chi phí tối đa mà một lần gọi verify_citations có thể dành cho các lần gọi judge (mặc định 1). max_cost_usd_total có thể giảm giới hạn này cho một lần gọi, nhưng không thể tăng |
IRIS_OTEL_ENDPOINT | Bật xuất trace OTLP/HTTP JSON theo cơ chế best-effort đến URL collector này |
IRIS_OTEL_SERVICE_NAME | Thuộc tính tài nguyên service.name cho xuất OTel (mặc định iris-eval) |
IRIS_OTEL_HEADERS | Các tiêu đề k=v cho xuất OTel, phân tách bằng dấu phẩy (ví dụ authorization=Bearer abc) |
IRIS_OTEL_TIMEOUT_MS | Thời gian chờ cho mỗi lần xuất (mặc định 15000) |
RATE_LIMIT_SALT | Chỉ dành cho website — tạo salt cho mã băm địa chỉ mà giới hạn tốc độ của playground iris-eval.com lưu giữ; máy chủ không bao giờ đọc biến này |
Bảo mật
Khi sử dụng truyền tải HTTP, Iris bao gồm:
- Xác thực bằng khóa API với phép so sánh an toàn theo thời gian (Bearer cho ứng dụng khách API; đăng nhập trình duyệt vào bảng điều khiển qua
?key=) - Mặc định chỉ cho phép CORS từ localhost
- Giới hạn tốc độ theo địa chỉ máy khách và theo phút: 600 yêu cầu đến API bảng điều khiển (
security.rateLimit.api) và 20 yêu cầu đến điểm cuối MCP (security.rateLimit.mcp), cả hai được đặt trongconfig.json; yêu cầu MCP vượt giới hạn sẽ nhận lỗi JSON-RPC nêu tên khóa - Các tiêu đề bảo mật Helmet
- Xác thực đầu vào bằng Zod trên mọi tuyến
- Regex an toàn trước ReDoS cho các quy tắc eval tùy chỉnh
- Giới hạn kích thước yêu cầu 1MB trên mọi phương thức truyền tải (
security.requestSizeLimit): HTTP trả lời413, stdio trả lời bằng lỗi JSON-RPC và giữ phiên mở - Giới hạn 100,000 phần tử mảng và khóa đối tượng trong một đầu vào, được đếm trước khi xác thực (
security.maxInputElements): đối số của lệnh gọi công cụ trên mọi phương thức truyền tải sẽ nhận kết quả lỗi nếu vượt giới hạn; nội dung yêu cầu của bảng điều khiển hoặc OTLP sẽ nhận413 - Lỗi xác thực trả về tối đa 20 vấn đề cùng tổng số (
issueCount), để câu trả lời luôn nhỏ dù yêu cầu sai đến đâu
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard
Khi đã đặt khóa, các ứng dụng khách API — ứng dụng khách MCP, SDK thu thập dữ liệu, POST /api/v1/traces — gửi Authorization: Bearer <key>. Để mở bảng điều khiển trong trình duyệt, hãy thêm khóa một lần vào bất kỳ URL nào của bảng điều khiển, http://localhost:6920/?key=<api key>: Iris đổi khóa lấy cookie phiên HttpOnly, SameSite=Lax rồi chuyển hướng đến cùng trang với khóa đã bị xóa khỏi thanh địa chỉ. Trang được mở mà không có phiên sẽ hiển thị biểu mẫu đăng nhập thực hiện cùng thao tác đổi khóa. Khóa không bao giờ được lưu trong trình duyệt; các phiên chỉ tồn tại trong tiến trình máy chủ (tối đa 256 phiên đang hoạt động cùng lúc; nếu tất cả đều đang hoạt động, yêu cầu đăng nhập mới sẽ bị từ chối thay vì loại bỏ một phiên).
Môi trường production
Nhiều khóa và xoay vòng không gián đoạn. security.apiKeys trong config.json chứa số lượng tùy ý các khóa bổ sung, mỗi khóa có một id và chính xác một trong hai trường keyFile (tệp có nội dung sau khi cắt khoảng trắng là khóa) hoặc keyHash (giá trị hex sha256 của khóa, để tệp cấu hình không chứa bí mật — printf %s "$KEY" | openssl dgst -sha256), cùng với trường expiresAt tùy chọn (ISO 8601), sau thời điểm đó khóa sẽ ngừng khớp ngay lập tức. Để xoay vòng: thêm khóa mới, chuyển các ứng dụng khách sang khóa đó, rồi xóa khóa cũ. Các khóa trong config.json và trong tệp khóa có hiệu lực mà không cần khởi động lại (0.20.0): với mỗi yêu cầu, máy chủ kiểm tra xem config.json hoặc tệp khóa mà nó trỏ đến có thay đổi hay không; nếu có, máy chủ đọc lại các khóa trước khi trả lời. Xóa khóa khỏi security.apiKeys hoặc xóa tệp khóa sẽ thu hồi khóa đó ở yêu cầu tiếp theo: yêu cầu đó bị từ chối và mọi phiên trình duyệt được mở bằng khóa đó đều bị đăng xuất. Nếu không thể đọc config.json (ví dụ: tệp mới chỉ được ghi một phần), hệ thống sẽ từ chối an toàn; cho đến khi khắc phục, chỉ chấp nhận khóa từ IRIS_API_KEY hoặc --api-key. Bản thân khóa trong IRIS_API_KEY hoặc --api-key, cũng như việc có bật xác thực hay không, vẫn chỉ thay đổi sau khi khởi động lại. Mọi khóa đều dùng để xác thực cho đến khi bị xóa hoặc hết hạn, cả qua Bearer lẫn đăng nhập trình duyệt; nhật ký khởi động nêu tên các ID. security.rateLimit.mcpKeyBy: "apiKey" tính ngân sách mỗi phút của điểm cuối MCP theo từng khóa thay vì theo địa chỉ máy khách, để nhiều agent dùng chung một địa chỉ vẫn có ngân sách riêng cho mỗi phút.
Nhiều ứng dụng khách. --transport http phục vụ số lượng tùy ý ứng dụng khách MCP tại cùng một địa chỉ: mỗi initialize mở một phiên riêng trên cùng một engine và kho dữ liệu, tối đa 256 phiên cùng lúc. Với stdio, mỗi ứng dụng khách khởi chạy tiến trình máy chủ riêng; các tiến trình đó dùng chung thư mục chính của Iris: quy tắc được triển khai, tắt hoặc xóa qua một tiến trình sẽ áp dụng cho mọi tiến trình khác trong vòng 20 ms; nhãn được ghi qua một tiến trình sẽ được các tiến trình khác đọc ngay sau đó; và nếu hai tiến trình thay đổi quy tắc cùng lúc thì không thay đổi nào bị mất.
Iris từ chối khởi động khi HTTP transport hoặc dashboard được bind ra ngoài loopback — 0.0.0.0, một địa chỉ LAN, một container — mà không có API key, và thông báo điều đó trong một câu có nêu IRIS_API_KEY. Điều này bao gồm cả docker run trần của image, vốn bind 0.0.0.0 bên trong container vì loopback không thể truy cập qua một cổng được publish. Loopback không có key vẫn hoạt động (kèm cảnh báo trên HTTP transport): ranh giới máy là biện pháp kiểm soát phơi lộ trong trường hợp đó.
# The image: pass a key
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
-e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server
# Compose: the file requires the variable and refuses before the container starts
IRIS_API_KEY="$(openssl rand -hex 32)" docker compose up
# A network you have already fenced some other way: run open, on purpose
IRIS_ALLOW_UNAUTHENTICATED=1 iris-eval --transport http --dashboard
Mở theo thiết kế trên máy chủ có key: GET /health trên transport và GET /api/v1/health trên dashboard trả lời không cần key và nằm ngoài mọi giới hạn tốc độ, theo cùng một định dạng: trạng thái, phiên bản, thời gian hoạt động, trình điều khiển SQLite, checks cho bộ nhớ lưu trữ, tệp quy tắc đã triển khai và các migration (đã áp dụng so với đã biết), trạng thái của chỉ mục tìm kiếm (search: sẵn sàng, hoặc tiến độ build tính theo tỷ lệ trên tổng số trace), và liệu có judge key hay không — không bao giờ là key, trace hay số lượng trace. status chỉ là ok khi mọi kiểm tra đều đạt; nếu không, nó là degraded với HTTP 503, được HEALTHCHECK của Docker image đọc. Mọi thứ khác cần Authorization: Bearer <key> hoặc một phiên trình duyệt. Việc lưu giữ chạy trên mọi máy chủ: trace và đánh giá cũ hơn retention.days (mặc định 30) sẽ bị xóa khi khởi động, sau khi máy chủ bắt đầu trả lời, và mỗi retention.sweepIntervalHours, theo từng bước ngắn để không khiến yêu cầu phải chờ lâu; --self-test in ra chính sách của bản cài đặt này, còn iris://capabilities / GET /api/v1/capabilities mang chính sách đó dưới dạng retention.
Webhook được kích hoạt khi có sự kiện (0.16.0): notify.webhook trong config.json (hoặc IRIS_WEBHOOK_URL và IRIS_WEBHOOK_SECRET) chỉ định một nơi nhận, và Iris gửi một thông điệp có chữ ký khi verdict không đạt, một phát hiện nghiêm trọng phủ quyết, chi phí là ngoại lệ, tỷ lệ lỗi của quy tắc thay đổi, hoặc một case lần đầu tiên được trả lời theo cả hai cách — ID, verdict, quy tắc và số liệu, không bao giờ có văn bản của agent. Ký đồng thời theo cách của Standard Webhooks và GitHub, thử lại với backoff, áp dụng thời gian chờ riêng cho từng agent và quy tắc, không bao giờ cản trở quá trình đánh giá; có sẵn nội dung cho Slack và Discord. docs/webhooks.md.
Dữ liệu của bạn trên đĩa
Mọi thứ Iris lưu đều nằm trong thư mục Iris home của bạn (~/.iris, hoặc IRIS_HOME). iris.db giữ nguyên từng chữ input và output của mọi trace — bao gồm mọi văn bản mà no_pii tiếp tục gắn cờ; phát hiện không xóa thông tin nhạy cảm trừ khi bạn yêu cầu: storage.redact: "critical_spans" trong config.json lưu đầu ra của từng lần đánh giá, thay các đoạn bị bộ phát hiện nghiêm trọng gắn cờ bằng [REDACTED:<pattern>] (mặc định tắt; các offset bằng chứng vẫn trỏ vào văn bản mà bên gọi đã thấy). storage.synchronous xác định thời điểm một lần ghi được lưu xuống đĩa: normal (mặc định) đồng bộ write-ahead log tại mỗi checkpoint, vì vậy nếu Iris gặp sự cố thì không mất dữ liệu và tệp không thể bị hỏng, nhưng mất điện hoặc hệ điều hành gặp sự cố có thể hoàn tác các lần ghi kể từ lần đồng bộ gần nhất; full đồng bộ mỗi lần commit và giữ lại dữ liệu qua cả hai trường hợp, với chi phí tăng khoảng 1.5 ms cho mỗi lần ghi. Khi khởi động, và sau đó mỗi retention.sweepIntervalHours (mặc định 24, 0 tắt bộ hẹn giờ), trace và đánh giá cũ hơn retention.days (mặc định 30, 0 tắt tính năng này, đặt trong config.json) sẽ bị xóa và write-ahead log được checkpoint. Có một thứ được giữ lại quá thời hạn: lần chạy baseline được ghim, cùng các đánh giá của nó, vì mọi lần chạy sau đều được so sánh với nó. Mỗi lần quét giữ lại một phần dữ liệu sẽ ghi vào log thông tin đó cùng với lần chạy và số lượng; bỏ ghim lần chạy thì lần quét tiếp theo sẽ xóa nó. Case và nhãn của dataset không phải trace hay đánh giá nên không bị quét xóa. Xóa một trace — bằng delete_trace hoặc qua lần quét — sẽ xóa văn bản của mọi đánh giá liên kết với trace đó (đầu ra, văn bản kỳ vọng và thông báo quy tắc) và đóng dấu erased_at; verdict, điểm số và offset bằng chứng vẫn được giữ lại. Mỗi lần xóa đều checkpoint write-ahead log trước khi trả về, vì vậy văn bản đã xóa không còn đọc được trong iris.db hoặc iris.db-wal (nếu lúc đó có tìm kiếm đang đọc tệp, hoặc tiến trình khác đang đọc hay ghi tệp, thao tác xóa sẽ trả về mà không chờ và văn bản sẽ rời khỏi tệp ngay khi thao tác hoàn tất). Để xóa mọi thứ ngay bây giờ, hãy dừng máy chủ và chạy --purge: lệnh này xóa mọi trace, span và đánh giá đã lưu, thu gọn cơ sở dữ liệu và cắt ngắn write-ahead log để văn bản biến mất khỏi đĩa, đồng thời giữ lại các quy tắc đã triển khai, nhật ký kiểm tra và tùy chọn của bạn. Trước khi một bản phát hành áp dụng migration cho iris.db hiện có, nó sao chép tệp sang vị trí bên cạnh (iris.db.<from>-to-<to>.<time>.bak, chỉ chủ sở hữu có quyền truy cập, giữ lại ba bản mới nhất; Hạ cấp): bản sao giữ nguyên các trace như trước, vì vậy lần quét lưu giữ sẽ xóa những trace cũ hơn retention.days và --purge sẽ xóa tất cả. Máy chủ thực hiện sao chép và migration sau khi đã trả lời client, trên một luồng riêng: các lệnh gọi tool, lần đọc resource và yêu cầu HTTP đến trong lúc đó sẽ chờ, tối đa 30 s mỗi yêu cầu, rồi bị từ chối bằng một câu cho biết máy chủ đang làm gì (IRIS_STORAGE_ERROR, có thể thử lại; HTTP 503 với Retry-After). Health vẫn trả lời trong suốt quá trình và cho biết nội dung nâng cấp đang thực hiện. Với 0.19.0 và 100,000 trace, mỗi trace là một vòng lặp agent, quá trình sao chép và migration mất khoảng 6 s. iris-eval ingest, --purge và --self-test vẫn nâng cấp trước khi làm bất cứ việc gì khác.
Iris không mã hóa dữ liệu khi lưu trữ. iris.db và các tệp write-ahead log được tạo với quyền chỉ dành cho chủ sở hữu (mode 600), còn thư mục Iris home được tạo với mode 700 (trên Windows, quyền truy cập tệp được kiểm soát bằng ACL). Cơ sở dữ liệu không lưu key của nhà cung cấp LLM: IRIS_ANTHROPIC_API_KEY và IRIS_OPENAI_API_KEY được đọc từ môi trường và không bao giờ được ghi xuống đĩa. Tuy nhiên, cơ sở dữ liệu lưu nguyên văn đầu vào và đầu ra của trace, vì vậy hãy đặt Iris home trên đĩa hoặc volume được mã hóa (FileVault, BitLocker, LUKS hoặc volume đám mây được mã hóa cho mount /data của Docker image).
Bản xuất — nút Export trên các trang Traces và Evaluations của dashboard, GET /api/v1/traces/export và /api/v1/evaluations/export, hoặc iris-eval export — mang theo văn bản đã lưu nguyên trạng, giống như cách dashboard hiển thị: đầu vào và đầu ra của trace nguyên văn, đầu ra đánh giá đã áp dụng storage.redact. Hãy xử lý tệp đã xuất như cơ sở dữ liệu mà nó được tạo ra từ đó.
Khắc phục sự cố
Bước đầu tiên: chạy bài tự kiểm tra
npx @iris-eval/mcp-server --self-test
Bài kiểm tra xác minh bộ nhớ lưu trữ, các bài đánh giá xác định và dashboard trong một thư mục tạm biệt lập, đồng thời in verdict cho từng bước — đầu ra lỗi sẽ nêu tên bước bị lỗi. Mã thoát 0 nghĩa là bản cài đặt hoạt động bình thường.
Iris không khởi động / ERR_MODULE_NOT_FOUND
Có thể bạn đang dùng phiên bản cũ hơn được lưu trong cache. Xóa cache npx rồi thử lại:
npx --yes @iris-eval/mcp-server@latest
Hoặc cài đặt toàn cục để tránh hoàn toàn các vấn đề về cache:
npm install -g @iris-eval/mcp-server@latest
npm install --ignore-scripts làm hỏng liên kết SQLite
Iris lưu trace bằng better-sqlite3, một module native tải xuống hoặc biên dịch liên kết của nó trong script cài đặt. Nếu script đó bị bỏ qua — --ignore-scripts trên dòng lệnh, ignore-scripts=true trong một .npmrc (thường gặp trên máy tính công ty), hoặc registry mirror loại bỏ postinstall — quá trình khởi động sẽ thất bại với một đoạn kết xuất dài "Could not locate the bindings file", liệt kê hàng tá đường dẫn đã thử. Hãy build lại riêng module đó:
npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3
Tool không xuất hiện trong Claude Code
Tool MCP chỉ được tải khi bắt đầu phiên. Sau khi thêm iris-eval, hãy khởi động lại phiên bằng /clear hoặc mở lại terminal.
Kiểm tra phiên bản
npx @iris-eval/mcp-server --version
Dòng đầu tiên của log khởi động cũng có phiên bản (Starting Iris MCP server vX.Y.Z), và --self-test in phiên bản trong phần tóm tắt. Với bản cài đặt toàn cục, npm ls -g @iris-eval/mcp-server hiển thị phiên bản đã cài.
Cập nhật
Mọi MCP client trên một máy dùng chung một cơ sở dữ liệu, ~/.iris/iris.db, và install ghim từng client vào bản phát hành đã ghi cấu hình của client đó. Khi một bản phát hành thay đổi schema của cơ sở dữ liệu, tiến trình đầu tiên của bản phát hành đó mở tệp sẽ nâng cấp tệp; từ đó trở đi, client vẫn bị ghim vào bản phát hành cũ hơn sẽ từ chối khởi động. Vì vậy, hãy chuyển mọi client cùng một lúc, trước hoặc ngay sau khi nâng cấp:
npx -y @iris-eval/mcp-server@latest install --upgrade
Lệnh này tìm mọi cấu hình client trên máy chạy Iris, chuyển từng ghim sang bản phát hành đó (giữ lại mọi nội dung bạn đã thêm vào mục cấu hình, chẳng hạn --dashboard hoặc một khối env), không thay đổi ghim sang bản phát hành mới hơn và mục chạy thứ khác ngoài npm package, đồng thời liệt kê những gì đã thực hiện. Hãy khởi động lại các client được nêu tên. install --list cho biết mỗi client chạy phiên bản Iris nào.
Có hai bản cài đặt nằm ngoài các tệp đó: Claude Desktop extension (iris-eval.mcpb) được cập nhật khi bạn mở bundle mới hơn, còn Claude Code plugin được cập nhật bằng claude plugin marketplace update iris-eval rồi claude plugin update iris-eval@iris-eval (và claude plugin update iris-eval-capture@iris-eval cho capture plugin).
Nâng cấp từ 0.19.x lên 0.20.0. 0.20.0 bổ sung chỉ mục tìm kiếm và các nội dung khác vào cơ sở dữ liệu (migration 015 trở đi). Sau khi bất kỳ tiến trình 0.20.0 nào mở ~/.iris/iris.db (Claude Desktop extension, npx iris-eval, hoặc npx @iris-eval/mcp-server không có phiên bản), client bị ghim vào 0.19.x sẽ dừng với This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, …. Thông báo đó đến từ 0.19.x và không thể thay đổi; cách khắc phục là chạy lệnh ở trên. Trước khi nâng cấp, 0.20.0 sao chép tệp sang vị trí bên cạnh, vì vậy bạn cũng có thể quay lại phiên bản cũ (xem bên dưới).
Lần khởi động nâng cấp cơ sở dữ liệu sẽ in ra stderr những gì đã thực hiện: bản sao đã tạo, các bản phát hành cũ hơn không còn mở được tệp, và mọi client trên máy này bị ghim vào một trong các bản đó, kèm theo lệnh cần chạy. --self-test đọc cơ sở dữ liệu mà không thay đổi gì và hiển thị cùng thông tin trước khi bạn khởi động bất cứ thứ gì.
Với bản cài đặt toàn cục, npm update -g @iris-eval/mcp-server, rồi iris-eval install --upgrade.
Hạ cấp
Bản phát hành nâng cấp cơ sở dữ liệu sẽ sao chép tệp trước, sang vị trí bên cạnh: iris.db.<from>-to-<to>.<time>.bak trong Iris home của bạn (<from> là bản phát hành gần nhất thay đổi schema của tệp, <to> là bản đã nâng cấp tệp; dòng khởi động in ra đường dẫn chính xác). Để quay lại:
- Dừng mọi MCP client và mọi tiến trình Iris khác đang dùng cơ sở dữ liệu.
- Giữ lại tệp đã nâng cấp phòng khi bạn quay lại: đổi tên
iris.dbthànhiris.db.upgraded, rồi xóairis.db-walvàiris.db-shmnếu chúng tồn tại. - Sao chép bản sao lưu vào
iris.db:cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db. - Ghim lại từng client vào bản phát hành cũ hơn:
npx -y @iris-eval/mcp-server@0.19.0 install <client>cho từng client (install --upgradekhông bao giờ chuyển client về bản cũ).
Các trace được lưu sau khi nâng cấp nằm trong iris.db.upgraded, không có trong bản sao lưu. Nếu không tạo được bản sao (dòng khởi động cho biết lý do, chẳng hạn đĩa đầy), bản phát hành cũ hơn không thể mở tệp đã nâng cấp; cách tiếp tục là install --upgrade.
Trình điều khiển bộ nhớ lưu trữ
Trên nền tảng không có better-sqlite3 dựng sẵn, quá trình cài đặt vẫn thành công. better-sqlite3 là dependency tùy chọn: khi npm không thể tải binary dựng sẵn cho Node và nền tảng của bạn, cũng không thể biên dịch binary (biên dịch cần Python và bộ công cụ C++ — bộ công cụ build C++ của Visual Studio trên Windows), npm sẽ in lỗi build, bỏ qua module và hoàn tất cài đặt. Khi đó Iris chạy bằng SQLite tích hợp sẵn trong Node và thông báo điều này: lúc khởi động, stderr in một dòng nêu lý do, còn --self-test hiển thị driver node: better-sqlite3 is not installed …. Để dùng lại trình điều khiển native, hãy cài đặt ở nơi có bản dựng sẵn hoặc bộ công cụ (npm install better-sqlite3 trong project; với bản cài đặt toàn cục, hãy cài lại Iris bằng npm install -g @iris-eval/mcp-server khi đã có bộ công cụ). CI cài đặt server đã đóng gói với quá trình build native bị buộc thất bại ở mọi thay đổi, đồng thời yêu cầu quá trình cài đặt hoàn tất và bài tự kiểm tra lưu rồi đọc được một trace bằng trình điều khiển tích hợp sẵn.
Iris lưu trữ mọi thứ trong một tệp SQLite, được mở bằng better-sqlite3 — một tiện ích bổ sung gốc được tải xuống hoặc biên dịch cho Node và nền tảng của bạn. Khi không thể tải mô-đun đó, Iris chuyển sang SQLite tích hợp sẵn của Node (node:sqlite, Node 22.13 trở lên) và đưa ra một cảnh báo trên stderr, vì vậy thiếu bản dựng sẵn chỉ khiến quá trình khởi động chậm hơn chứ không bị lỗi hoàn toàn. Iris cũng làm tương tự trước khi tải mô-đun đó đối với một better-sqlite3 được biên dịch trên máy của bạn bằng các header của Node 24.19 trở lên rồi chạy trên Node 24.19 đến 24.21: trên các phiên bản đó, một tệp nhị phân như vậy sẽ làm toàn bộ tiến trình bị hủy ngay lần đầu giải phóng một câu lệnh (Assertion failed: (env) != nullptr, nodejs/node#65446). Node 24.22.0 có bản sửa lỗi này, và Iris tải tệp nhị phân trên phiên bản đó. npm rebuild better-sqlite3 thay thế nó bằng tệp nhị phân dựng sẵn, an toàn trên mọi phiên bản. IRIS_SQLITE_DRIVER=node chủ động chọn bản tích hợp sẵn, còn native cấm dùng phương án dự phòng. Bản tích hợp sẵn được mở khi đã tắt tải tiện ích mở rộng và tắt trusted_schema; Node tự in dòng ExperimentalWarning: SQLite is an experimental feature trên stderr khi tải, và Iris không ẩn dòng này. --self-test và GET /health cho biết trình điều khiển đang được dùng; mọi con số trên trang kiểm chứng đều được đo bằng trình điều khiển gốc, và bộ kiểm thử chạy trên cả hai trong CI.
Phiên bản Node.js
Iris yêu cầu Node.js 22.13 trở lên. Node 20 đã hết vòng đời vào ngày 2026-04-30 và không được hỗ trợ; Node 18 đã hết vòng đời vào tháng 4 năm 2025.
Phiên bản tối thiểu là 22.13 thay vì 22.0 vì 22.13.0 là bản phát hành đầu tiên có node:sqlite. Nhờ đó, đây là phiên bản đầu tiên mà mọi bản cài đặt Iris được hỗ trợ đều có trình điều khiển lưu trữ thứ hai: khi không thể tải tiện ích bổ sung gốc better-sqlite3, Iris chuyển sang SQLite tích hợp sẵn của Node thay vì không thể khởi động. Trước 22.13 — và trong toàn bộ vòng đời của Node 20 — chỉ có duy nhất một trình điều khiển, và thiếu bản dựng sẵn đồng nghĩa với việc không thể khởi động.
node --version # Must be v22.13.0 or newer
Windows: không cần cmd /c
/doctor của Claude Code có thể đề xuất bọc npx bằng cmd /c. Việc này không cần thiết và gây ra sự cố phân tích đường dẫn. Hãy dùng trực tiếp npx:
# Correct
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server
# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx -y @iris-eval/mcp-server"
Nếu Iris hữu ích với bạn, hãy cân nhắc gắn sao cho kho mã — việc này giúp người khác tìm thấy dự án.
Được cấp phép theo MIT.