Iris

ทางการ

เซิร์ฟเวอร์ประเมินและสังเกตการณ์เอเจนต์แบบ MCP-native พร้อมการบันทึก trace การประเมินคุณภาพผลลัพธ์ การติดตามต้นทุน กฎการประเมินในตัว 12 ข้อ แดชบอร์ดแบบเรียลไทม์ และการตรวจจับ PII

คุณทำอะไรได้บ้างด้วย Iris MCP?

  • บันทึกและให้คะแนนการรัน — ขอให้ผู้ช่วยบันทึกการรันของเอเจนต์ไปยัง Iris และประเมินผลลัพธ์ จากนั้นดูคำตัดสินและคะแนนบนแดชบอร์ด
  • ตรวจสอบกฎด้านความปลอดภัยและค่าใช้จ่าย — เรียกใช้กฎแบบกำหนดผลลัพธ์แน่นอนที่มีมาให้ 28 ข้อ สำหรับ PII, prompt injection, ตัวบ่งชี้การหลอน และเกณฑ์ค่าใช้จ่าย โดยไม่เรียกใช้ LLM
  • ตรวจสอบและแก้ไขกฎ — แสดงรายการกฎที่มีมาให้ แล้วตรวจสอบหรือเปลี่ยนแปลงกฎเหล่านั้นได้ เนื่องจากกฎทุกข้อสามารถตรวจสอบและแก้ไขได้
  • เพิ่มกฎที่กำหนดเอง — โหลดกฎที่คุณเขียนเป็นโค้ดผ่าน eval.plugins ใน config.json โดยระบุแฮชไฟล์ไว้
  • เปรียบเทียบการรัน — เปิดการรันสองรายการที่ใช้คำถามเดียวกันเพื่อดูเทียบกัน พร้อมช่วงเวลาในมุมมอง Runs ของแดชบอร์ด
  • กำหนดให้ CI ผ่านตามคำตัดสิน — เรียกใช้ ingest พร้อม --evaluate --fail-on any เพื่อให้จ็อบล้มเหลวเมื่อมีคำตัดสินใดที่ไม่ใช่ผ่าน

เอกสาร

Iris — เลิกปล่อยเอเจนต์ตามความรู้สึก

CI OpenSSF Scorecard OpenSSF Best Practices npm version License: MIT Install in Cursor Install in VS Code

ส่งการทำงานของเอเจนต์ให้ Iris แล้วขอให้ตัดสินคุณภาพ ความปลอดภัย และค่าใช้จ่าย — บนเครื่องของคุณ โดยไม่ต้องใช้ SDK หรือบัญชี โปรเจกต์เอเจนต์ส่วนใหญ่ตรวจคุณภาพด้วยการรันพรอมป์ต์ที่จำได้ไม่กี่รายการแล้วกวาดตาดูผลลัพธ์ Iris แทนที่วิธีนั้นด้วยตัวเลขที่คุณตรวจสอบได้: การทำงานของเอเจนต์จะถูกบันทึกลงฐานข้อมูล SQLite บนดิสก์ของคุณ กฎในตัว 28 ข้อให้คะแนนอย่างกำหนดแน่นอน — PII, prompt injection, ตัวบ่งชี้การหลอนข้อมูล, เกณฑ์ค่าใช้จ่าย และการเรียกใช้เครื่องมือของเอเจนต์ — ฟรี ไม่มีการเรียก LLM และมีตัวตัดสิน LLM ให้เลือกใช้ โดยจำกัดค่าใช้จ่ายต่อการประเมินอย่างเข้มงวด เพื่อจัดการคำถามเชิงความหมาย กฎทุกข้อสามารถตรวจสอบและแก้ไขได้ เพราะตัวตัดสินที่คุณตรวจสอบไม่ได้ก็เป็นแค่ความรู้สึกที่มีตัวเลขกำกับ ใช้สัญญาอนุญาต MIT ไม่มี telemetry ไม่มีอะไรออกจากเครื่องของคุณ เว้นแต่คุณจะเปิดใช้สิ่งใดสิ่งหนึ่งต่อไปนี้: ปลายทาง OpenTelemetry (IRIS_OTEL_ENDPOINT) ซึ่งส่งออก trace ไปยัง collector ที่คุณระบุ; ตัวตัดสิน LLM ที่ใช้คีย์ของคุณเอง ซึ่งส่งข้อความที่นำไปตัดสินให้ผู้ให้บริการนั้น และตัวตรวจสอบการอ้างอิงจะดึงหน้าเว็บที่ผลลัพธ์อ้างถึง; หรือ webhook ซึ่งส่ง id, คำตัดสิน และชื่อกฎไปยังที่อยู่ที่คุณตั้งไว้ โดยไม่ส่งข้อความ

ต้องใช้ Node.js 22.13 ขึ้นไป ตรวจสอบด้วย node --version.

The demo: Failures, a failure opened, two runs compared

ฐานข้อมูลสาธิต บันทึกโดย scripts/demo-media.mts; ซอร์สอยู่ที่ demo.mp4. ภาพนิ่ง: dashboard-overview.png.

ดูความล้มเหลวบนหน้าจอภายใน 60 วินาที

ไม่ต้องเชื่อมต่อเอเจนต์ ไม่ต้องตั้งค่า — ใช้คำสั่งเดียว:

npx @iris-eval/mcp-server --demo

คำสั่งนี้สร้างฐานข้อมูลสาธิต — เอเจนต์ขนาดเล็กห้าตัว การทำงานตลอดสองสัปดาห์ และคำตัดสินทั้งหมดมาจากเอนจินเอง — แล้วเปิดแดชบอร์ดโดยใช้ฐานข้อมูลนั้นที่ http://localhost:6920 (เบราว์เซอร์ของคุณจะเปิดโดยอัตโนมัติเมื่อรันครั้งแรก) แดชบอร์ดจะแสดงหน้า Failures: สิ่งที่ล้มเหลว เรียงจากรายการที่แย่ที่สุดและใหม่ที่สุดก่อน โดยการ์ดแต่ละใบระบุกฎและหลักฐาน ลองคลิกดูได้ เช่น การรั่วไหลของ PII ที่กฎความปลอดภัยตรวจพบ คำสั่งแฝงในโพสต์ฟอรัมที่ตัวสรุปทำตาม ตัวเลขที่ไม่มีอยู่ในเอกสารต้นทาง การเปรียบเทียบการทำงานสองครั้งบนคำถามชุดเดิมสิบสองข้อพร้อมช่วงความเชื่อมั่น (Runs) กฎกำหนดเองที่นำไปใช้แล้วและกฎที่หยุดไว้พร้อมแถวบันทึกการตรวจสอบ และคะแนนจากตัวตัดสิน LLM ที่ล้มเหลวพร้อมเหตุผลประกอบ

ข้อมูลสาธิตอยู่ในฐานข้อมูลแยกต่างหาก (demo.db ในไดเรกทอรีหลักของ Iris — ~/.iris บน macOS/Linux, %USERPROFILE%\.iris บน Windows) และไม่ปะปนกับ trace จริงของคุณ ลบข้อมูลทั้งหมดได้ด้วยคำสั่งเดียว:

npx @iris-eval/mcp-server --demo-clear

เชื่อมต่อเอเจนต์ของคุณ

ก่อนอื่น ตรวจสอบว่าการติดตั้งทำงานบนเครื่องนี้ — คำสั่งนี้ทำงานแบบออฟไลน์และไม่เปิดข้อมูลใด ๆ ของคุณ:

npx @iris-eval/mcp-server --self-test   # exit 0 = healthy

จากนั้นเพิ่ม Iris ลงใน MCP client ของคุณ ใช้คำสั่งเดียวเพื่อเขียนไฟล์กำหนดค่าของ client โดยเก็บเซิร์ฟเวอร์อื่นทั้งหมดไว้ และตรึงเวอร์ชันที่คุณเรียกใช้:

npx -y @iris-eval/mcp-server install claude-code

ไคลเอนต์: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list แสดงรายการที่พบในเครื่องนี้ พร้อม Iris ที่แต่ละรายการเรียกใช้และไฟล์ที่อ่าน; install <client> --uninstall นำ Iris ออกได้ หากอัปเกรด ไคลเอนต์ทั้งหมดใช้ฐานข้อมูลร่วมกัน จึงควรย้ายพร้อมกันด้วย install --upgrade (การอัปเดต). รีสตาร์ตไคลเอนต์เพื่อโหลดการตั้งค่า

Claude Desktop: คลิกครั้งเดียว ตั้งแต่รุ่น 0.20.0 เป็นต้นไป แต่ละรุ่นจะมี iris-eval.mcpb ซึ่งเป็น MCP Bundle: ดาวน์โหลด รุ่นล่าสุด เปิดไฟล์ แล้ว Claude Desktop จะแสดงกล่องโต้ตอบการติดตั้ง ไม่มีรายการใดจำเป็นต้องกรอก — คีย์ Anthropic หรือ OpenAI สำหรับตัวตัดสิน LLM เป็นตัวเลือก และแดชบอร์ดเป็นสวิตช์ที่ปิดไว้ตั้งแต่แรก Bundle มีแพ็กเกจ npm และ dependencies รวมอยู่แล้ว จึงไม่ต้องติดตั้งอย่างอื่น: Claude Desktop เรียกใช้ผ่าน Node ที่มาพร้อมโปรแกรม หาก Node นั้นเป็นเวอร์ชัน 22.13 ขึ้นไป (Claude Desktop 1.1.6679 มาพร้อม 24.13) และ Iris จัดเก็บ trace ด้วย SQLite ที่มีมาใน Node ใน ~/.iris เดียวกับที่การติดตั้งอื่นใช้ บันทึกประจำรุ่นอธิบายวิธีตรวจสอบลายเซ็นและการรับรองการสร้าง

Iris ทำงานได้กับ MCP client ทุกตัว และ client ทุกตัวที่ระบุไว้มีแถวบอกวิธีตรวจสอบ ตรวจสอบแล้วในการรัน CI ทุกครั้ง: Claude Code, Gemini CLI — ไคลเอนต์จริงเริ่ม Iris จากการตั้งค่าที่ตัวติดตั้งเขียนไว้และรายงานว่าเชื่อมต่อแล้ว (claude mcp list, gemini mcp list) บน Linux, macOS และ Windows; hook ของปลั๊กอินบันทึกข้อมูลของ Claude Code ก็ทดสอบผ่านสคริปต์จริงเช่นกัน กำหนดค่าตามเอกสาร MCP ของแต่ละไคลเอนต์ — ตัวติดตั้งเขียนไฟล์ตามที่ไคลเอนต์แต่ละตัวระบุไว้ ทั้งตำแหน่งและรูปแบบที่เอกสารกำหนด (บล็อก mcpServers, servers ของ VS Code, context_servers ของ Zed, TOML ของ Codex) โดยเก็บความคิดเห็นและเซิร์ฟเวอร์อื่นทั้งหมดไว้ และการทดสอบหน่วยตรวจสอบเส้นทางและตัวเขียนทุกรูปแบบตามเอกสาร: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI แต่ละแถวมีแหล่งข้อมูลและวันที่อ่าน: https://iris-eval.com/clients. หากต้องการทำเอง ให้ใช้บล็อกเดียว รวมแดชบอร์ดด้วย:

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
    }
  }
}

ไคลเอนต์ของคุณจะแสดงเครื่องมือทั้งสิบสองรายการของ Iris เมื่อเชื่อมต่อ และแดชบอร์ดจะให้บริการที่ http://localhost:6920. ตอนนี้ส่งข้อความนี้ให้เอเจนต์ของคุณ:

บันทึกงานล่าสุดนั้นลง Iris แล้วประเมินผลลัพธ์

trace จะปรากฏบนแดชบอร์ดพร้อมคะแนน หากต้องการใช้ MCP server แบบ headless ให้ลบ --dashboard ออกจาก args — คุณเปิดแดชบอร์ดเดิมได้ทุกเมื่อด้วย npx @iris-eval/mcp-server --dashboard.

สิ่งหนึ่งที่ควรรู้ไว้ก่อน: MCP tools จะถูกเรียกเมื่อโมเดลตัดสินใจเรียก Iris ไม่ได้ดักจับเอเจนต์ของคุณ ดังนั้น trace จะถูกบันทึกเมื่อเอเจนต์ขอให้บันทึก — ไม่ว่าจะเพราะคุณสั่ง หรือเพราะโค้ดของคุณเรียก tools โดยตรง ขอให้เอเจนต์ “บันทึกสิ่งนี้ลง Iris แล้วประเมินผล” แล้วเอเจนต์ก็จะทำให้ หากต้องการบันทึกโดยไม่ขึ้นกับการตัดสินใจของโมเดล POST /api/v1/traces ทำสิ่งนั้นได้พอดี — โค้ดของคุณส่ง trace ผ่าน HTTP ธรรมดา โดยไม่มีโมเดลอยู่ในวงจร (ดู docs/http-ingest.md). CLI และ host hooks ใน แผนงาน จะเป็นไคลเอนต์ขนาดเล็กที่ใช้ endpoint เดียวกัน

บันทึกผ่าน HTTP (ไม่มีโมเดลอยู่ในวงจร)

ingest endpoint อยู่บน พอร์ตแดชบอร์ด — โดยปริยายคือ 6920 ไม่ใช่พอร์ต MCP transport — และจะมีอยู่เฉพาะตอนที่แดชบอร์ดกำลังทำงานเท่านั้น ส่ง --dashboard (หรือตั้งค่า IRIS_DASHBOARD=true); การใช้ --transport http เพียงอย่างเดียว ไม่ ได้เริ่มแดชบอร์ด และคำขอไปยังพอร์ต transport จะส่งกลับ 404 เมื่อแดชบอร์ดทำงานอยู่ สิ่งใดก็ตามที่ส่งคำขอ HTTP ได้ก็สามารถบันทึก trace ได้ — และเลือกให้รันการประเมินแบบกำหนดแน่นอนในคำขอเดียวกันได้ด้วย GET /api/v1/capabilities บนพอร์ตเดียวกันจะบอกว่าเซิร์ฟเวอร์นี้ตัดสินอะไรได้บ้าง แต่ละกฎต้องใช้อะไร สถานะของตัวตัดสินพร้อมขั้นตอนเปิดใช้ และข้อจำกัดต่าง ๆ — เป็นออบเจ็กต์เดียวกับที่ MCP resource iris://capabilities ให้บริการ — เพื่อให้ผู้เรียกผ่าน HTTP ได้ข้อมูลพื้นฐานแบบเดียวกับที่ MCP client ได้รับเมื่อ initialize:

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"
  }'

ส่งกลับ 201 พร้อม trace_id ที่จัดเก็บไว้และผลการประเมิน (ในโหมด --demo endpoint จะปฏิเสธการเขียนด้วย 403 เพื่อไม่ให้ข้อมูลสาธิตปะปนกับข้อมูลของคุณ) endpoint รับ body แบบเดียวกับ tool log_trace และอยู่หลัง middleware stack เดียวกับส่วนอื่นของแดชบอร์ด: โดยปริยายจะ bind กับ loopback และมีตัวป้องกัน DNS rebinding พร้อม Bearer auth หากคุณตั้งค่าไว้ ข้อเท็จจริงตรงไปตรงมาสองข้อ: endpoint ยอมรับการเขียนโดยไม่ต้องยืนยันตัวตน เว้นแต่ Iris จะเริ่มทำงานด้วย --api-key (หรือ IRIS_API_KEY) — โดยปริยาย การ bind กับ loopback เป็นสิ่งที่จำกัดให้ใช้งานได้เฉพาะบนเครื่องของคุณ ดังนั้นให้ตั้งคีย์ก่อน bind นอก loopback; และข้อมูลที่จัดเก็บจะเป็นข้อความตามต้นฉบับ — input และ output จะถูกบันทึกลง iris.db ตรงตามที่ส่งมา รวมถึงข้อความใด ๆ ที่ no_pii ตรวจพบในภายหลัง ดูสัญญาการทำงาน รายละเอียดฟิลด์ และความหมายของข้อผิดพลาดฉบับเต็มได้ที่ docs/http-ingest.md.

บันทึกทุกเทิร์นของ Claude Code (ตัวเลือกเสริม)

/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval

ปลั๊กอินตัวที่สองซึ่งติดตั้งแยกต่างหาก: hook ของปลั๊กอินจะบันทึกพรอมป์ต์ของแต่ละเทิร์น การเรียกใช้เครื่องมือ (รวมถึงรายการที่ล้มเหลว พร้อมข้อผิดพลาดที่เอเจนต์ได้รับ) และคำตอบสุดท้าย โดยใช้พรอมป์ต์เป็นคีย์ จึงส่งการเรียกใช้เครื่องมือของเทิร์นที่ถูกขัดจังหวะและของ sub-agent ที่ทำงานเบื้องหลังได้ด้วย จากนั้นส่งข้อมูลให้ iris-eval ingest แบบ detached โดยปกปิด span สำคัญในข้อความประเมินที่จัดเก็บไว้ — เป็นการบันทึกที่ไม่ขึ้นกับการตัดสินใจเรียก tool ของโมเดล เทิร์นที่จบลงด้วยข้อผิดพลาด API จะถูกจัดเก็บโดยไม่ผ่านการตัดสิน; หากโมเดลบันทึกเทิร์นนั้นด้วย จะเก็บ trace ทั้งสองรายการไว้ และของปลั๊กอินจะระบุว่าเป็นของโมเดล ปลั๊กอินไม่แสดงผล ไม่ขัดขวาง และไม่ส่งอะไรไปที่ใด การติดตั้ง iris-eval เพียงอย่างเดียวไม่เปลี่ยนลูปการทำงานของเทิร์น ข้อจำกัดและวิธีนำออก: 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": []}

ไคลเอนต์ขนาดเล็กที่ใช้ HTTP API ของเซิร์ฟเวอร์เวอร์ชัน 0.16.0 ขึ้นไป และมีการกำหนดเวอร์ชันแยกต่างหาก — iris_eval.__version__ และหน้า PyPI แสดงหมายเลขเวอร์ชันของไคลเอนต์ ซึ่งไม่ใช่เวอร์ชันของเซิร์ฟเวอร์: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), รองรับทั้ง sync และ async, คำตอบที่มีชนิดข้อมูลกำกับ, ข้อความปฏิเสธจากเซิร์ฟเวอร์เอง — และปลั๊กอิน pytest: fixture iris และ assert_iris(output, expect="pass") ที่ตรวจยืนยันสถานะของคำตัดสิน packages/python/README.md.

บันทึกทุกการเรียก OpenAI และ 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' });

ครอบ client ของผู้ให้บริการเพียงครั้งเดียว แล้วการเรียกโมเดลแต่ละครั้งจะกลายเป็น OpenTelemetry GenAI span หนึ่งรายการที่ส่งไปยัง OTLP door จัดเก็บพร้อมอินพุต เอาต์พุต การใช้โทเค็น และการเรียกใช้เครื่องมือ แล้วให้คะแนน: เป็นการบันทึกที่ไม่ขึ้นกับการเรียก tool ของโมเดล wrap_openai / wrap_anthropic ในไคลเอนต์ Python; wrapOpenAI, wrapAnthropic และ irisMiddleware สำหรับ Vercel AI SDK ใน @iris-eval/sdk ทั้งสองรายการยังไม่เผยแพร่ (รุ่น iris-eval ถัดไปบน PyPI; @iris-eval/sdk สร้างจากซอร์สจนกว่าจะมีรุ่น npm แรก) ครอบคลุม streams, stream helpers ของ SDK และการเรียกใช้เครื่องมือ โดยไม่เปลี่ยน client ต้นฉบับ และแม้ Iris จะหยุดทำงาน การเรียกก็ยังไม่ล้มเหลว — packages/sdk/README.md, packages/python/README.md.

ให้คะแนนทุกการทำงานของ LangChain และ LangGraph

from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})

การทำงานระดับบนสุดแต่ละครั้งจะกลายเป็น trace หนึ่งรายการ (การทำงานนั้น การเรียกโมเดล การเรียกใช้เครื่องมือ และโหนดกราฟในรูป GenAI spans) พร้อมอินพุต เอาต์พุต การเรียกใช้เครื่องมือ การใช้โทเค็น และคำตัดสิน Python อยู่ในไคลเอนต์ (pip install iris-eval, 0.2.0 ขึ้นไป), JavaScript ใช้ @iris-eval/langchain (อยู่ใน repository นี้ แต่ยังไม่เผยแพร่บน npm) ทั้งสองแบบผ่านการพิสูจน์ใน CI โดยใช้แอป LangGraph จริงกับโมเดลจำลองที่กำหนดสคริปต์ไว้; การส่งออก OpenTelemetry ของ LangSmith เองก็พิสูจน์ด้วยวิธีเดียวกัน — docs/otel-recipes.md.

ด่าน CI ไม่ต้องใช้เซิร์ฟเวอร์

npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any

any ทำให้ job ล้มเหลวเมื่อคำตัดสินใดไม่ใช่ pass: ทั้งกรณีที่ล้มเหลวและกรณีที่ไม่ได้ตรวจสอบคำตัดสิน ระบุเกณฑ์เพียงข้อเดียวแทนด้วย --fail-on detector_veto เพื่อให้ล้มเหลวเฉพาะเมื่อไม่ผ่านเกณฑ์นั้น

หรือใช้ GitHub Action (0.16.0) ซึ่งทำให้ job ล้มเหลวตามคำตัดสินที่คุณระบุ เขียนใบรับรองผลลงในสรุปของ job และโพสต์เป็นความคิดเห็นเดียวใน pull request โดยอัปเดตความคิดเห็นเดิม: uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 พร้อม traces: traces.ndjson — docs/ci-gate.md. ประตูที่สี่ (0.15.0): POST /v1/traces บนพอร์ตแดชบอร์ดรับ OTLP/HTTP แบบ JSON หรือ protobuf ที่เครื่องมือวัด OpenTelemetry ของคุณส่งออกอยู่แล้ว (exporter ของ Python SDK รองรับเฉพาะ protobuf ดังนั้นนี่จึงเป็นประตูสำหรับ Python ด้วย) และแต่ละ OTLP trace จะกลายเป็น Iris trace พร้อม spans — docs/otel-integration.md; มีสูตรตัวอย่างหนึ่งชุดต่อเฟรมเวิร์ก (Pydantic AI, Google ADK, LangGraph via LangSmith, CrewAI, OpenAI Agents SDK ใน Python และ JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK และ Mastra) โดยแต่ละชุดผ่านการพิสูจน์ด้วย fixture ใน docs/otel-recipes.md ingest อ่าน JSON trace หนึ่งรายการ (หรือ NDJSON หนึ่งรายการต่อบรรทัด) จาก stdin หรือไฟล์ จัดเก็บ แล้วประเมินด้วยกฎชุดเดียวกับที่ evaluate_output ใช้ทุกประการ พิมพ์ JSON หนึ่งบรรทัดต่อ trace พร้อมผลตัดสินและเหตุผลประกอบ และออกด้วยรหัส 1 เมื่อผลตัดสินตรงกับ --fail-on --dataset <id|label> จำกัด gate ให้ตรวจเฉพาะ case keys ใน dataset (POST /api/v1/datasets นำ case keys ของ run มาใส่ใน dataset ได้) ดังนั้น job จะล้มเหลวเฉพาะกับ cases ที่คุณเลือก สูตรฉบับเต็ม รหัสออก และเหตุผลประกอบทั้งแปดแบบอยู่ใน docs/ci-gate.md

เขียนกฎเป็นโค้ด

eval.plugins ใน config.json โหลดกฎที่คุณเขียนไว้ — ES module ที่ default export เป็น { name, kind, mechanism, version, needs, evaluate(ctx) } — โดยตรึงไฟล์ด้วย sha256 ของไฟล์ ดังนั้นหากไฟล์เปลี่ยนไปหลังจากตรึงไว้ ระบบจะปฏิเสธการเริ่มทำงานแทนที่จะเรียกใช้ ปลั๊กอินที่โหลดแล้วจะทำงานเหมือนกฎที่มีมาให้ และแสดงใน list_rules ใต้ plugins ข้อกำหนด hash recipe และสิ่งที่ปลั๊กอินส่งคืนได้: docs/plugins.md

ใช้ engine ในโปรเซสของคุณเอง

นำเข้า evaluation engine ได้ — ไม่ต้องมีเซิร์ฟเวอร์ ฐานข้อมูล หรือโมเดล:

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

ใช้ engine กฎ และ composer ชุดเดียวกับที่เซิร์ฟเวอร์เรียกใช้; builtInRules(), createCustomRule(), compose() และตัวอ่าน published-accuracy ก็ export ไว้ข้างกันด้วย

ไคลเอนต์แบบมีชนิดข้อมูลสำหรับ 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

ทุกประตูใช้ body เดียวกัน: เป็น body ที่ log_trace และ iris-eval ingest ยอมรับ หากปฏิเสธ จะโยน IrisClientError พร้อมประโยคและ status ของเซิร์ฟเวอร์เอง ทั้งสอง subpath ได้รับการตรวจสอบจาก tarball ที่แพ็กแล้วในทุก build

ตรวจสอบการติดตั้ง

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 จะสร้าง Iris home ให้ก่อนหากยังไม่มี และตรวจสอบว่าเขียนได้หรือไม่ (หากเขียนไม่ได้ จะออกด้วยรหัส 1 พร้อมระบุ path) รายงานตำแหน่ง search index ของฐานข้อมูล (สมบูรณ์แล้ว, จำนวน traces ที่ background build ทำดัชนีไปแล้ว หรือไม่มี FTS5 ใน SQLite นี้) อ่าน schema ของฐานข้อมูล (หากเวอร์ชันนี้หรือ MCP client ที่ตรึงไว้กับรุ่นเก่ากว่าเปิดไม่ได้ จะออกด้วยรหัส 1 พร้อมวิธีแก้) จากนั้นจึงเรียกใช้การตรวจสอบ — storage round-trip, SSN ที่ฝังไว้และ injection ที่ฝังไว้ซึ่ง safety rules ตรวจจับได้, การเริ่มทำงานของแดชบอร์ด และตัวป้องกัน DNS rebinding — ภายใน temp home ที่แยกไว้ ฐานข้อมูลจริงของคุณจะถูกอ่านเท่านั้น ไม่มีการเปลี่ยนแปลง ทุกสิ่งที่ Iris เขียนจะอยู่ในไดเรกทอรีเดียวที่เรียกว่า Iris home: ~/.iris ตามค่าเริ่มต้น (%USERPROFILE%\.iris บน Windows) หรือที่ใดก็ตามที่ IRIS_HOME ชี้ไป ที่นั่นคือที่อยู่ของ iris.db, config.json, custom-rules.json, audit.log, preferences.json และไฟล์เดโม; กำหนด IRIS_HOME ให้ชี้ไปยังไดเรกทอรี scratch เพื่อทดลองใช้ Iris โดยไม่แตะต้องข้อมูลจริงของคุณ

ตั้งค่าตามเครื่องมือ
ไคลเอนต์สถานะความหมายอ่าน
Claude Codeverifiedมีการทดสอบที่เรียกใช้ไคลเอนต์จริงในทุก CI run2026-09-25
Claude Desktopclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Cursorclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Devin Desktop (Windsurf)claimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Continueclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
VS Codeclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Clineclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Zedclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
OpenAI Codex CLIclaimedตั้งค่าตามเอกสาร MCP ของไคลเอนต์เอง; มี unit test ตรวจสอบ path และรูปแบบที่ตัวติดตั้งใช้2026-09-25
Gemini CLIverifiedมีการทดสอบที่เรียกใช้ไคลเอนต์จริงในทุก CI run2026-09-25

ทุกรายการพร้อมรายละเอียดสิ่งที่ตรวจสอบ: iris-eval.com/clients จะไม่ระบุว่าไคลเอนต์ใดรองรับ หากไม่มีรายการอยู่ในตาราง

npx -y @iris-eval/mcp-server install <client> เขียนข้อมูลเหล่านี้ให้คุณทั้งหมด หากตั้งค่าด้วยตนเอง ให้ทำตามขั้นตอนของแต่ละไคลเอนต์:

Claude Desktop

แก้ไขไฟล์ MCP config ของคุณ:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

เพิ่ม JSON config ด้านบน แล้วรีสตาร์ต Claude Desktop

Claude Code

claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server

จากนั้นรีสตาร์ตเซสชัน (/clear หรือเปิดใหม่) เพื่อให้โหลด tools

หมายเหตุสำหรับ Windows: อย่าใช้ wrapper cmd /c เพราะทำให้เกิดปัญหาในการแยกวิเคราะห์ path คำสั่ง npx ใช้งานได้โดยตรง

Cursor

เพิ่ม JSON config ด้านบนลงใน ~/.cursor/mcp.json (ทุกโปรเจกต์) หรือ .cursor/mcp.json ใน workspace โดยใส่ "type": "stdio" ในรายการ iris-eval — เอกสารของ Cursor ระบุว่าจำเป็นต้องมี

Devin Desktop (Windsurf)

เพิ่ม JSON config ด้านบนลงใน mcp_config.json: ~/.config/devin/mcp_config.json บน macOS และ Linux, %APPDATA%\devin\mcp_config.json บน Windows

Continue

บันทึก JSON config ด้านบนเป็นไฟล์แยกในโฟลเดอร์ mcpServers ของ Continue: ~/.continue/mcpServers/iris-eval.json (ทุก workspace) หรือ .continue/mcpServers/iris-eval.json ใน workspace เดียว

VS Code (native MCP)

เพิ่มลงใน .vscode/mcp.json ใน workspace ของคุณ (หมายเหตุ: VS Code ใช้ servers ไม่ใช่ mcpServers):

{
  "servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"]
    }
  }
}

Cline

เปิดแผง MCP Servers ของ Cline → Configure MCP Servers แล้วเพิ่ม JSON config mcpServers ด้านบนลงใน cline_mcp_settings.json (~/.cline/data/settings/cline_mcp_settings.json ซึ่ง Cline ใช้ร่วมกันใน VS Code, JetBrains และ CLI)

Zed

เพิ่มลงใน settings.json ของ Zed:

{
  "context_servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"],
      "env": {}
    }
  }
}

OpenAI Codex CLI

เพิ่มลงใน ~/.codex/config.toml:

[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]

Gemini CLI

เพิ่ม JSON config mcpServers ด้านบนลงใน ~/.gemini/settings.json Gemini CLI เชื่อมต่อกับ MCP servers เฉพาะในโฟลเดอร์ที่เชื่อถือเท่านั้น: หาก gemini mcp list แสดงว่า iris-eval เป็น Disabled ให้เรียกใช้ /permissions ในโฟลเดอร์นั้น

ไคลเอนต์อื่นที่รองรับ MCP

Iris เป็น MCP server มาตรฐานแบบ stdio — ใช้คำสั่ง npx @iris-eval/mcp-server เพียงคำสั่งเดียว ไม่ต้องใช้ SDK หรือแก้ไขโค้ด หากไคลเอนต์ของคุณรองรับ MCP ก็รองรับ Iris ด้วย รูปแบบ config ของไคลเอนต์อาจเปลี่ยนแปลงได้ หากไม่แน่ใจ ให้ตรวจสอบเอกสาร MCP ของไคลเอนต์ แล้วชี้ไปยังคำสั่งนั้น

วิธีติดตั้งอื่น ๆ

# 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

เคล็ดลับ: การติดตั้งแบบ global (npm install -g) จะจัดเก็บ traces ไว้อย่างถาวรที่ ~/.iris/iris.db เมื่อใช้ npx traces จะยังคงอยู่ในตำแหน่งเดิม แต่เริ่มทำงานช้าลงเนื่องจากต้อง resolve แพ็กเกจ

อิมเมจ container และไดเรกทอรี MCP ที่แสดงรายการ Iris:

Docker Glama Score PulseMCP mcp.so

สิ่งที่คุณจะได้รับ

การบันทึก Traceต้นไม้ span แบบลำดับชั้น พร้อม latency ต่อการเรียกใช้ tool, การใช้ token และค่าใช้จ่ายเป็น USD จัดเก็บใน SQLite และค้นหาได้ทันที
การประเมินผลลัพธ์กฎในตัว 28 ข้อ ครอบคลุม 4 หมวด: ความครบถ้วน ความเกี่ยวข้อง ความปลอดภัย และค่าใช้จ่าย การตรวจจับ PII (21 รูปแบบ: SSN, บัตรเครดิต, โทรศัพท์, อีเมล, IBAN, DOB, MRN, IP, API key, หนังสือเดินทาง รวมถึง token ของ AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean, ข้อมูลรับรองภายใน URL, การกำหนดค่าที่ตั้งชื่อเป็นความลับ, บล็อก private key แบบ PEM และ seed phrase; วันเกิด หมายเลขเวชระเบียน หนังสือเดินทาง และ seed phrase จะทำงานเฉพาะเมื่ออยู่ติดกับป้ายกำกับของตน ตามที่ออกแบบไว้), prompt injection (38 รูปแบบ ทั้งวลีและโครงสร้าง), การตรวจจับผลลัพธ์จำลอง, การตรวจจับภาพหลอน (สัญญาณการแต่งเติมหรือขัดแย้งกับบริบท 25 แบบ — ส่ง input เพื่อเทียบกับเนื้อหาต้นทางของ agent) และกฎ trajectory หกข้อที่อ่านสิ่งที่ agent ทำ: การเรียก tool ที่ล้มเหลวโดยไม่มีการยอมรับ, การเรียกซ้ำ (ตามการเรียก ตามลำดับที่ซ้ำ หรือแยกตามเป้าหมายเมื่อคุณส่ง tools), การเรียกที่ arguments ไม่ผ่าน JSON Schema ของ tool เองและ agent ไม่ได้ลองใหม่, ไฟล์ ไดเรกทอรี หรือ URL ที่คำตอบอ้างถึงแต่ไม่ปรากฏในสิ่งที่ agent อ่าน, คำสั่งที่มาจาก TOOL RESULT แล้วถูกทำตามโดยการเรียกครั้งถัดไป และงานที่ใช้การเรียก tool มากกว่างบ step ของคุณ อีกสองข้อจะเปรียบเทียบ run กับ run ก่อนหน้าของ case เดียวกันจาก agent เดียวกัน โดยไม่ต้องมีใครเขียน expectation: การกระทำที่ run ก่อนหน้าไม่เคยทำ และ step ที่ run ก่อนหน้าทุกครั้งทำแต่ run นี้ไม่ได้ทำ trajectory รับข้อมูลได้ในรูปแบบ tool_calls หรือเป็น OpenTelemetry TOOL spans เพิ่มกฎที่กำหนดเองได้ด้วย Zod schemas
LLM-as-Judgeให้คะแนนเชิงความหมายได้โดยเลือกใช้ Anthropic หรือ OpenAI — ใช้ API key ของคุณเอง มีเทมเพลตเจ็ดแบบ เมื่อตั้งค่า IRIS_RELEVANCE_JUDGE_MODEL แล้ว answers_the_ask จะเรียก judge ของ relevance และทำให้คำตอบที่นอกประเด็นไม่ผ่าน หากไม่ได้ตั้งค่า กฎจะตรวจคำถามด้วยการจับคู่คำศัพท์และให้คำแนะนำ มีเพดานค่าใช้จ่ายต่อ eval แบบตายตัว (IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL ค่าเริ่มต้น $0.25) และเปิดเผยราคาต่อ eval ในผลลัพธ์
การมองเห็นค่าใช้จ่ายรวมค่าใช้จ่ายของ agent ทั้งหมดในช่วงเวลาใดก็ได้ ตั้งเกณฑ์งบประมาณ และรับการแจ้งเตือนเมื่อ agent ใช้จ่ายเกิน Trace ที่ส่งจำนวน token และโมเดลมาแต่ไม่มีค่าใช้จ่าย (พบได้ใน traces จาก OpenTelemetry และเฟรมเวิร์กส่วนใหญ่) จะคำนวณราคาตามราคาปลีกของโมเดลและระบุว่าเป็นค่าประมาณทุกที่ที่แสดง; pricing.models ใน config.json ใช้กำหนดราคาสำหรับโมเดลที่ไม่มีในตารางในตัว — docs/cost.md
Web DashboardUI โหมดมืดแบบเรียลไทม์ที่แสดงข้อผิดพลาดก่อน โดยเรียงรายการที่แย่ที่สุดและใหม่ที่สุดไว้ด้านบน — แสดง trace พร้อมค้นหาข้อความเต็มในทุก trace, ผล eval, รายละเอียดค่าใช้จ่าย และ command palette (⌘K) สำหรับค้นหากฎ traces และ evals ของคุณ
Local-firstทุกอย่างอยู่ใน SQLite บนดิสก์ของคุณ เซิร์ฟเวอร์ที่โฮสต์เองไม่ต้องมีบัญชีหรือสมัครใช้งาน และไม่ส่ง telemetry การเชื่อมต่อ HTTP ขาออกจะเกิดขึ้นเฉพาะเมื่อคุณเลือกใช้: API key สำหรับ LLM-judge ของคุณเอง, การดึงข้อมูลอ้างอิง, OTel exporter ที่คุณกำหนดค่า หรือ webhook ที่คุณตั้งไว้

สิ่งที่จะพัฒนาต่อไป: แผนผังความสามารถ — ทุกคำถามที่ถาม Iris ได้เกี่ยวกับทุกหัวข้อ พร้อมระบุสิ่งที่มีและสิ่งที่ยังขาด — และ สามแนวทาง

วัดผล ไม่ใช่กล่าวอ้าง

กฎที่มีมาให้ทุกข้อมีค่าความแม่นยำ (precision), ค่าการเรียกคืน (recall) และ F1 ที่เผยแพร่พร้อมช่วงความเชื่อมั่น 95% โดยวัดจากคลังข้อมูลที่ติดป้ายกำกับซึ่งอยู่ใน repository นี้ (proof/corpus/) และสร้างใหม่ได้ด้วยคำสั่งเดียว — npm run proof — โดยทำงานออฟไลน์ ไม่ต้องใช้คีย์ และไม่มีโมเดลเข้ามาเกี่ยวข้อง ตัวเลขเหล่านี้มีอยู่สองประเภทที่แตกต่างกัน และหน้าเว็บจะไม่นำมารวมกัน: กฎบางข้อวัดเทียบกับป้ายกำกับที่โมเดลกำหนดโดยอ่านข้อผิดพลาดนั้นเอง ซึ่งเป็นการวัดการตรวจจับ ส่วนกฎที่เหลือจะตรวจสอบเทียบกับคำจำกัดความที่บันทึกไว้ของกฎนั้น โดยนำไปใช้แยกกัน ซึ่งแสดงให้เห็นว่าโค้ดทำตามสูตรของกฎ แต่ไม่ได้บอกว่าสูตรนั้นตรวจจับข้อผิดพลาดได้หรือไม่ proof/RESULTS.md และหน้าพิสูจน์หลักฐานจะระบุประเภทของแต่ละกฎ CI จะวัดผลใหม่ทุกครั้งที่มี pull request และล้มเหลวหากตัวเลขที่ commit ไว้ต่างจากผลที่โค้ดสร้างขึ้น ดังนั้นกฎจะเปลี่ยนไปโดยที่ตัวเลขไม่เปลี่ยนตามไม่ได้ ดูตัวเลขได้ที่ iris-eval.com/proof และใน proof/RESULTS.md; วิธีสร้างคลังข้อมูล สิ่งที่คลังข้อมูลนี้ไม่ใช่ และวิธีอ่านช่วงความเชื่อมั่น อยู่ใน docs/proof.md คลังข้อมูลนี้เป็นข้อมูลสังเคราะห์และติดป้ายกำกับโดยโมเดล — ยังรอการติดป้ายกำกับแบบปกปิดโดยมนุษย์ และหน้าเว็บระบุเรื่องนี้ไว้; node proof/blind-sample.mjs จะสุ่มตัวอย่างที่ทำซ้ำได้เพื่อหาข้อสรุป

เครื่องมือ MCP

Iris ลงทะเบียนเครื่องมือสิบสองรายการที่เอเจนต์ซึ่งรองรับ MCP เรียกใช้ได้ — การติดตามและวงจรชีวิตของกฎ การเปรียบเทียบระหว่างการรัน การประเมินโดย LLM และการตรวจสอบการอ้างอิงเชิงความหมาย:

  • log_trace — บันทึกการทำงานของเอเจนต์พร้อม spans, การเรียกใช้เครื่องมือ, การใช้โทเค็น และค่าใช้จ่าย; ส่ง evaluate: true เพื่อให้ประเมินผลในการเรียกครั้งเดียวกัน
  • evaluate_output — ประเมินคุณภาพผลลัพธ์ตามกฎด้านความครบถ้วน ความเกี่ยวข้อง ความปลอดภัย และค่าใช้จ่าย (ฮิวริสติก กำหนดผลแน่นอน ไม่มีค่าใช้จ่าย)
  • get_traces — ค้นหา traces ที่จัดเก็บไว้ด้วยตัวกรอง การแบ่งหน้า และการรองรับช่วงเวลา และค้นหารันที่เอเจนต์พูดบางอย่างด้วย q: ค้นหาข้อความเต็มในอินพุต เอาต์พุต ค่าการเรียกใช้เครื่องมือ และข้อมูลเมตา จัดอันดับผลลัพธ์ พร้อมทำเครื่องหมายคำที่ตรงกัน
  • list_rules — แสดงรายการกฎประเมินแบบกำหนดเองที่นำไปใช้งานแล้ว (อ่านอย่างเดียว)
  • deploy_rule — ลงทะเบียนกฎประเมินแบบกำหนดเองใหม่ เพื่อให้ทำงานกับทุก evaluate_output ในหมวดหมู่นั้น
  • delete_rule — ลบกฎแบบกำหนดเองที่นำไปใช้งานแล้ว (ทำลายข้อมูล แต่เรียกซ้ำได้อย่างปลอดภัย)
  • delete_trace — ลบ trace ที่จัดเก็บไว้หนึ่งรายการตาม ID (ทำลายข้อมูล จำกัดขอบเขตตาม tenant)
  • evaluate_with_llm_judge — ประเมินเชิงความหมายผ่าน LLM (Anthropic หรือ OpenAI) มีเทมเพลตเจ็ดแบบ: accuracy, helpfulness, safety, correctness, faithfulness, task_completed, relevance จำกัดค่าใช้จ่ายและแจ้งราคาต่อการประเมิน ใช้ API key ของคุณเอง (IRIS_ANTHROPIC_API_KEY หรือ IRIS_OPENAI_API_KEY) — Iris ไม่พร็อกซีหรือส่งต่อการเรียกใช้ LLM
  • verify_citations — ดึงข้อมูลการอ้างอิงจากเอาต์พุต (แบบมีหมายเลข ผู้แต่ง-ปี URL, DOI) ดึงแหล่งข้อมูลผ่านตัวแก้ไขที่ป้องกัน SSRF และอนุญาตเฉพาะโดเมน แล้วใช้ LLM judge ตรวจสอบว่าแต่ละแหล่งข้อมูลสนับสนุนข้อความที่อ้างถึงจริงหรือไม่ การเชื่อมต่อ HTTP ขาออกต้องเลือกเปิดใช้ ต้องใช้ BYOK เช่นเดียวกับ evaluate_with_llm_judge
  • compare_runs — การเปลี่ยนแปลงทำให้เอเจนต์แย่ลงหรือไม่? เปรียบเทียบการรันสองครั้งของผลการประเมินที่จัดเก็บไว้: ใช้การทดสอบแบบจับคู่ที่แน่นอนเมื่อทั้งสองรันใช้คีย์กรณีทดสอบร่วมกัน ใช้ช่วงความเชื่อมั่นของผลต่างในกรณีอื่น ตอบอย่างตรงไปตรงมาว่า “บอกไม่ได้” พร้อมจำนวนกรณีที่ต้องใช้ หรือระบุว่า “เทียบเท่ากันภายในค่าคลาดเคลื่อน” แต่ละกฎมีการทดสอบด้านเดียวของตัวเอง และปรับแก้ร่วมกัน (Benjamini–Hochberg) เพื่อไม่ให้กฎยี่สิบข้อสร้างผลถดถอยขึ้นมาเอง
  • compare_traces — เอเจนต์ตอบคำถามเดิมได้อย่างสม่ำเสมอเพียงใด? แสดงอัตราผ่านรายกรณีพร้อมช่วงความเชื่อมั่น เรียงกรณีที่ผลไม่คงที่ไว้ก่อน และคำนวณอัตรารวมโดยคำนึงถึงการทดสอบซ้ำ
  • evaluate_runs — ให้คะแนน trace ทุกตัวในการรันใหม่ภายใต้กฎปัจจุบัน แล้วสร้างเป็นรันใหม่ เพื่อไม่ให้เข้าใจผิดว่าการเปลี่ยนกฎคือการเปลี่ยนแปลงของเอเจนต์

เปิดใช้ LLM judge (ไม่บังคับ; กฎแบบกำหนดผลแน่นอนไม่ต้องใช้)

  1. รับ API key จาก Anthropic หรือ OpenAI
  2. ใส่คีย์ไว้ใน environment ของโปรเซสที่รัน Iris ไม่ใช่แค่ใน shell ของคุณ สำหรับ Claude Code, Claude Desktop, Cursor และ MCP client ส่วนใหญ่ ให้ใส่ในบล็อก "env" ของรายการ iris-eval ในการตั้งค่า MCP ของคุณ — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (ใช้ IRIS_OPENAI_API_KEY สำหรับคีย์ OpenAI) สำหรับ Docker ให้ใช้ -e IRIS_ANTHROPIC_API_KEY=... ในคำสั่ง run สำหรับ HTTP หรือ CI ให้ export คีย์ก่อนเริ่ม iris-eval
  3. เริ่มเซสชัน MCP ใหม่ โปรเซสที่กำลังทำงานอยู่จะไม่เห็นตัวแปรที่ตั้งค่าหลังจากเริ่มโปรเซสแล้ว
  4. ตรวจสอบจากภายใน client ของคุณ: อ่าน iris://capabilities — judge.enabled ต้องเป็น true หากตั้งคีย์ไว้ใน shell แต่ไม่ได้ส่งต่อไปยังโปรเซสที่ client เรียกใช้ คีย์นั้นจะใช้ไม่ได้ เว้นแต่จะระบุไว้ในการตั้งค่า บนเครื่อง ให้ใช้ npx @iris-eval/mcp-server --self-test เพื่อแสดงบรรทัด judge สำหรับ shell นั้น และ GET /api/v1/health จะแสดง judge.enabled บนแดชบอร์ดที่กำลังทำงาน
  5. การควบคุมค่าใช้จ่าย: แต่ละครั้งที่เรียกใช้จะถูกจำกัดด้วย IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (ค่าเริ่มต้น 0.25 USD) และจะถูกปฏิเสธก่อนมีค่าใช้จ่ายใด ๆ หากกรณีที่แพงที่สุดอาจเกินขีดจำกัดนี้ การเรียก judge ทุกครั้งที่ Iris ทำโดยใช้คีย์ของคุณจะนับรวมในงบประมาณรายวันเดียวกัน คือ IRIS_LLM_JUDGE_DAILY_BUDGET_USD (ค่าเริ่มต้น 1 USD ต่อวัน UTC); เมื่อใช้เกินงบแล้ว จะไม่มีการเรียกใช้จนกว่าจะถึงเที่ยงคืน UTC Iris เรียกผู้ให้บริการโดยตรงด้วยคีย์ของคุณและไม่ทำหน้าที่เป็นพร็อกซี
  6. ไม่บังคับ: ตั้งค่า IRIS_RELEVANCE_JUDGE_MODEL เป็น ID ของโมเดลที่มีราคา (เช่น claude-haiku-4-5) เพื่อให้ answers_the_ask ถาม judge ว่าแต่ละคำตอบตอบโจทย์ที่ถามหรือไม่ และให้ไม่ผ่านหากตอบนอกประเด็น การประเมินแต่ละครั้งที่มีอินพุตจะเรียก judge หนึ่งครั้ง โดยใช้คีย์ของคุณและอยู่ภายใต้ขีดจำกัดข้างต้น การมีคีย์เพียงอย่างเดียวจะไม่เปิดใช้ฟีเจอร์นี้ แต่ละครั้งที่เรียกจะส่งอินพุตและเอาต์พุตนั้นไปยังผู้ให้บริการโมเดล โดยแทนที่ข้อมูลส่วนบุคคลและข้อมูลรับรองที่มีแฟล็ก no_pii ก่อน (IRIS_RELEVANCE_JUDGE_REDACT=off จะส่งข้อมูลตามเดิม) การเรียกนี้นับรวมในงบประมาณรายวันดังกล่าว และเรียกได้ไม่เกิน IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST ครั้งต่อคำขอ (ค่าเริ่มต้น 20); เมื่อเกินขีดจำกัดใดขีดจำกัดหนึ่ง answers_the_ask จะอ่านโจทย์ตามคำศัพท์และอธิบายเหตุผล

เมื่อกำหนดค่า IRIS_OTEL_ENDPOINT แล้ว การเรียก log_trace จะส่งออกข้อมูลแบบ OTLP/HTTP JSON ไปยัง OpenTelemetry collector ใดก็ได้ด้วยวิธี best-effort (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb ฯลฯ) ดู docs/otel-integration.md

วิธีตัดสิน passed

evaluate_output ส่งคืนทั้ง score และแฟล็ก passed — ทั้งสองตอบคำถามคนละข้อ:

  • score (0..1) คือค่าเฉลี่ยถ่วงน้ำหนักของกฎที่ทำงาน — เป็นระดับคุณภาพ
  • passed คือคำตัดสินว่าจะนำขึ้นใช้งานหรือไม่ และจะไม่พิจารณาคะแนนเลย ตัวจัดการจะอ่านกฎแต่ละข้อโดยพิจารณาจากประเภทของข้อกล่าวอ้างที่กฎนั้นใช้: นโยบายที่คุณกำหนดไว้จะเป็นตัวตัดสิน; ตัวตรวจจับที่สำคัญจะมีสิทธิ์ยับยั้ง; การตรวจสอบที่สำคัญซึ่งถูกเรียกใช้แต่ไม่สามารถให้คำตอบได้ จะทำให้คำตัดสินเป็น unknown (passed: false) แทนที่จะถือว่าผ่าน; ตัวตรวจจับที่เหลือจะรวมกันเป็นความน่าจะเป็นเดียวว่าเอาต์พุตไม่ดี โดยถ่วงน้ำหนักตามอัตราความสูญเสียที่คุณระบุใน eval.falsePassCost (ค่าเริ่มต้น 1 ดังนั้นจุดตัดคือ 0.5) verdict.basis ระบุชั้นที่เป็นผู้ตัดสิน และ verdict.by ระบุกฎ ส่วน verdict.also แสดงทุกชั้นถัดไปที่จะเป็นผู้ตัดสินด้วย; interpretations[] อธิบายว่าทำไมกฎที่ไม่ผ่านจึงไม่ได้เป็นผู้ตัดสิน และการตั้งค่าใดจะเปลี่ยนผลนั้น พร้อมระบุคำถามที่ไม่ได้รับการประเมินและอินพุตที่จะทำให้ประเมินได้

การละเมิดความปลอดภัยที่เกิดขึ้นจริงจะทำให้ไม่ผ่านทันที โดยค่าเริ่มต้น no_pii, no_injection_patterns และ no_blocklist_words เป็น กฎสำคัญ: หากข้อใดไม่ผ่าน ผลการประเมินจะรายงาน passed: false ไม่ว่ากฎอื่นจะได้คะแนนดีเพียงใด และคำตอบจะระบุตัวการใน critical_failures ไม่สามารถเฉลี่ยการรั่วไหลของ SSN ให้หายไปได้ กฎที่มีมาให้ข้อใดเป็นกฎสำคัญนั้นกำหนดได้ในการตั้งค่าการนำไปใช้งาน (eval.criticalRules / eval.nonCriticalRules) เช่นเดียวกับตัวตรวจจับที่ให้รายงานผลเท่านั้น (eval.advisoryRules); ผลลัพธ์ของแต่ละกฎจะมีแฟล็ก critical และ criticalSource ที่มีผลจริง และ list_rules จะแสดงรายการกฎที่เซิร์ฟเวอร์นี้ใช้ กฎแบบกำหนดเองที่นำไปใช้งานด้วย severity: "high" หรือ "critical" จะทำให้ไม่ผ่านทันทีเช่นเดียวกัน; ระดับความรุนแรง low/medium มีผลต่อคะแนนเท่านั้น ข้อจำกัดสำคัญที่ควรทราบและระบุไว้เหมือนกันในทุกส่วน: กฎสำคัญที่ ข้ามการตรวจสอบ (บริบทขาดหาย คำจำกัดความใช้ไม่ได้ หรือ regex ถูกยุติเมื่อถึงงบประมาณ sandbox) ยังไม่ได้ประเมินเอาต์พุต จึงไม่มีสิทธิ์ยับยั้ง — กฎดังกล่าวทุกข้อจะระบุไว้ใน critical_skipped เกตที่ต้องปิดเมื่อไม่ผ่านจะถือว่า critical_skipped ที่ไม่ว่างเป็น unknown ไม่ใช่ clean และอาจถือว่าการข้าม budgetExceeded ใด ๆ ใน rule_results มีผลเช่นเดียวกัน

สำหรับเกต CI: หากไม่ระบุ eval_type จะเรียกใช้ทุกชุดกฎ — ความครบถ้วน ความเกี่ยวข้อง ความปลอดภัย ค่าใช้จ่าย และกฎแบบกำหนดเองทั้งหมด — และคำตอบจะระบุ eval_type: "all" พร้อม note ว่าใช้ค่าเริ่มต้น รวมถึงแผนที่ categories แยกตามชุดกฎ แต่ละแถวมี state: คำตัดสินที่อ่านจากกฎในชุดนั้น ดังนั้นแถวหนึ่งจะไม่แสดงว่าผ่าน หากกฎที่ทำให้การประเมินไม่ผ่านอยู่ในชุดนั้น ชุดกฎที่ไม่มีสิ่งให้ประเมิน (ค่าใช้จ่ายที่ไม่มี cost_usd, ความเกี่ยวข้องที่ไม่มี input) จะรายงาน state: "unknown" และ passed: null ในส่วนนั้น — หมายถึงไม่ได้ประเมิน ไม่ใช่ไม่ผ่าน — และจะไม่นับรวมในการตัดสิน คำตอบจะแสดง eval_type ที่ทำงานเสมอ เพื่อให้เกตของคุณตรวจสอบความครอบคลุมได้ ให้ใช้ passed เป็นเกณฑ์สำหรับคำตัดสิน และระบุชื่อชุดกฎเฉพาะเมื่อต้องการให้รันในขอบเขตที่แคบลง

การเขียนกฎแบบกำหนดเอง

เพิ่มกฎได้สองวิธี กฎ แบบอินไลน์ จะส่งไปพร้อมกับการเรียก evaluate_output ครั้งเดียว (custom_rules ได้สูงสุด 10 ข้อต่อการเรียก); กฎเหล่านี้จะทำงานร่วมกับชุดกฎ eval_type ที่คุณเลือก หรือทำงานเพียงลำพังด้วย eval_type: "custom" กฎ ที่นำไปใช้งานแล้ว จะลงทะเบียนครั้งเดียวด้วย deploy_rule คงอยู่ใน custom-rules.json ภายใต้โฮมของ Iris และทำงานกับทุก evaluate_output ใน evalType ของกฎนั้นในอนาคต รูปแบบคำจำกัดความเหมือนกันทั้งสองวิธี:

ฟิลด์จำเป็นรายละเอียด
nameใช่1–80 อักขระ; ปรากฏเป็น ruleName ในผลลัพธ์
typeใช่ต้องเป็นหนึ่งใน regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold
configใช่คีย์สำหรับประเภทนั้น: pattern (+ flags ซึ่งไม่บังคับ) สำหรับ regex สองประเภท · min_length / max_length (จำนวนอักขระ) · keywords (+ threshold ซึ่งไม่บังคับ, 0–1, ค่าเริ่มต้น 1 = ต้องมีครบทุกคำ) สำหรับประเภทคำสำคัญสองประเภท · {} สำหรับ json_schema · max_cost ในหน่วย USD สำหรับ cost_threshold
weightไม่น้ำหนักในคะแนน; ค่าเริ่มต้น 1

deploy_rule ครอบคำจำกัดความด้วย name, description ที่ไม่บังคับ, evalType (completeness · relevance · safety · cost · custom) และ severity ระดับความรุนแรงระบุความหมายของ การไม่ผ่าน: low/medium มีผลลดคะแนนเท่านั้น; high/critical ทำให้การประเมินไม่ผ่านทันที — passed: false โดยระบุกฎไว้ใน critical_failures — ไม่ว่าคะแนนถ่วงน้ำหนักจะเป็นเท่าใด กฎที่ข้ามการตรวจสอบ (กฎ cost_threshold ที่ไม่มี cost_usd หรือ regex ที่ถูกยุติเมื่อถึงงบประมาณ sandbox 100 ms) ยังไม่ได้ประเมินเอาต์พุต และจะแสดงอยู่ใน critical_skipped แทน นำกฎสำคัญที่ห้ามชื่อโฮสต์ภายในในทุกสิ่งที่เอเจนต์พูดไปใช้งาน:

{
  "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" }
  }
}

คำตอบคือกฎที่บันทึกไว้แล้ว — เก็บ id ไว้สำหรับ delete_rule:

{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }

ตั้งแต่ evaluate_output ถัดไปที่มี eval_type: "safety" ผลลัพธ์ที่กล่าวถึง db-primary.internal.example จะกลับมาเป็น passed: false พร้อมกับ critical_failures: ["no_internal_hostnames"] — แม้ว่ากฎความปลอดภัยในตัวทั้งห้าข้อจะผ่านทั้งหมด และคะแนนถ่วงน้ำหนักอยู่ที่ 0.895 รูปแบบ Regex ต้องผ่านการตรวจสอบ ReDoS ขณะ deploy และทำงานใน sandbox worker ภายใต้กำหนดเวลาสูงสุด 100 ms เสมอ list_rules แสดงสิ่งที่ deploy อยู่ ส่วนตัวสร้างกฎของแดชบอร์ดจะสร้างรูปแบบเดียวกันจากความล้มเหลวที่คุณคลิกดู ดูข้อมูลอ้างอิงฉบับเต็ม การให้คะแนนแยกตามประเภท และตัวอย่างประกอบได้ที่ docs/custom-rules.md

สคีมาเครื่องมือและการกำหนดค่าฉบับเต็ม: iris-eval.com

โฮสต์เองและใช้งานฟรี

Iris ทำงานบนเครื่องของคุณหรือโครงสร้างพื้นฐานของคุณเอง แกนหลักแบบโอเพนซอร์สใช้งานได้ฟรีภายใต้สัญญาอนุญาต MIT โดยไม่มีข้อจำกัดการใช้งานและไม่ต้องมีบัญชี ขณะนี้กำลังพิจารณาบริการจัดเก็บข้อมูลแบบโฮสต์ ประวัติการใช้งานร่วมกันในทีม และการแจ้งเตือน แต่ยังไม่ได้เริ่มพัฒนา หากสิ่งเหล่านี้เป็นประโยชน์กับคุณ โปรดแจ้งเราที่ hello@iris-eval.com

เรายึดมั่นในคำมั่นสองข้อ: สิ่งที่ใช้ฟรีในวันนี้จะไม่ถูกย้ายไปอยู่หลังระบบชำระเงิน และ จะไม่มีการกล่าวอ้างว่าผ่านการรับรองด้านการปฏิบัติตามข้อกำหนดก่อนที่จะได้รับการรับรองจริง

ตัวอย่าง

ชุมชน

การกำหนดค่าและความปลอดภัย

อาร์กิวเมนต์ CLI

Flagค่าเริ่มต้นคำอธิบาย
--transportstdioประเภทการขนส่ง: stdio หรือ http
--port3000พอร์ตสำหรับการขนส่ง HTTP
--db-path~/.iris/iris.dbพาธฐานข้อมูล SQLite
--config~/.iris/config.jsonพาธไฟล์การกำหนดค่า
--api-key—API key สำหรับการยืนยันตัวตน HTTP (การขนส่งและแดชบอร์ด รวมถึง POST /api/v1/traces)
--dashboardfalseเปิดใช้แดชบอร์ดเว็บ และเป็นวิธีเดียวที่ทำให้ endpoint ingest ของ POST /api/v1/traces เริ่มทำงาน — จะไม่เริ่มทำงานโดยปริยายพร้อมกับ --transport http
--dashboard-port6920พอร์ตแดชบอร์ด
--dashboard-host127.0.0.1ที่อยู่ bind ของแดชบอร์ด ค่าเริ่มต้นคือ loopback — แดชบอร์ดไม่มีการยืนยันตัวตน เว้นแต่จะตั้งค่า --api-key ดังนั้นการ bind นอก loopback จะเปิดเผยประวัติ trace ทั้งหมดของคุณ
--demofalseสร้างฐานข้อมูลสาธิต (แยกจาก trace จริงของคุณ) และให้บริการแดชบอร์ดโดยใช้ฐานข้อมูลนั้น
--demo-clearfalseลบฐานข้อมูลสาธิตแล้วออก
--self-testfalseเรียกใช้การวินิจฉัยการติดตั้งแบบออฟไลน์ใน home ชั่วคราวที่แยกไว้ แล้วออก (0 = ปกติ, 1 = การตรวจสอบล้มเหลว) นอกจากนี้ยังอ่านฐานข้อมูลที่กำหนดค่าไว้แบบอ่านอย่างเดียว และจะแจ้งว่าล้มเหลวเมื่อเวอร์ชันนี้หรือ MCP client ที่ pin ไว้ไม่สามารถเปิดฐานข้อมูลได้
--purgefalseลบ trace, span และ evaluation ทั้งหมด ที่จัดเก็บไว้จากฐานข้อมูลที่กำหนดค่าไว้ บีบอัดไฟล์ และตัดทอน write-ahead log เพื่อไม่ให้ข้อความที่ลบแล้วยังคงค้างอยู่บนดิสก์ โดยจะเก็บกฎที่ deploy แล้ว บันทึกการตรวจสอบ และค่ากำหนดไว้ การดำเนินการนี้ย้อนกลับไม่ได้ ให้หยุดเซิร์ฟเวอร์ Iris ที่กำลังทำงานอยู่ก่อน — ไฟล์จะถูกบีบอัดในตำแหน่งเดิม ปฏิเสธการใช้ร่วมกับ --demo, --demo-clear หรือ --self-test
--version—พิมพ์เวอร์ชันเปล่า (เช่น 1.2.3) ไปยัง stdout แล้วออกด้วยรหัส 0 โดยไม่อ่านข้อมูลใด ๆ ใน home ของ Iris

มีสามคำสั่งที่รับอาร์กิวเมนต์ของตัวเองแล้วออกจากโปรแกรม: iris-eval ingest โหลด trace จากไฟล์หรือ stdin (ด่านตรวจ CI ที่ไม่ต้องใช้เซิร์ฟเวอร์), iris-eval export traces|evaluations --format csv|jsonl เขียนข้อมูลที่จัดเก็บไว้ซึ่งกรองตามรายการในแดชบอร์ดไปยัง stdout หรือ --out (docs/api-reference.md), และ iris-eval install <client> เขียน Iris ลงในการกำหนดค่าของ MCP client — --uninstall นำออก, --list แสดง client ที่พบในเครื่องนี้และ Iris ที่แต่ละ client ใช้อยู่, --upgrade ย้าย client ทุกตัวที่เรียกใช้ Iris มาเป็นเวอร์ชันนี้ (เชื่อมต่อเอเจนต์ของคุณเอง, การอัปเดต). ไม่มีคำสั่งใดเริ่มเซิร์ฟเวอร์

config.json จะได้รับการตรวจสอบเมื่อ Iris เริ่มทำงาน หาก Iris ไม่รู้จักคีย์ — เช่น พิมพ์ eval.critcalRules ผิด หรือใช้คีย์จากเครื่องมืออื่น — หรือค่ามีชนิดข้อมูลไม่ถูกต้อง ระบบจะปฏิเสธการเริ่มทำงานพร้อมข้อความหนึ่งประโยคที่ระบุชื่อคีย์แบบเต็ม คีย์ที่น่าจะตั้งใจใช้ หรือชนิดข้อมูลที่ต้องการ ไม่มีข้อมูลใดในไฟล์ที่ถูกละเลยโดยไม่แจ้งให้ทราบ

ตัวแปรสภาพแวดล้อม

เอกสาร --help ระบุตัวแปรทุกตัว หากตั้งค่าทั้งคู่ flag ของ CLI จะมีลำดับความสำคัญเหนือกว่าตัวแปรสภาพแวดล้อม

ตัวแปรคำอธิบาย
IRIS_TRANSPORTประเภทการขนส่ง (stdio หรือ http)
IRIS_HOSTที่อยู่ bind ของการขนส่ง HTTP (ค่าเริ่มต้น 127.0.0.1)
IRIS_PORTพอร์ตของการขนส่ง HTTP (1-65535, ค่าเริ่มต้น 3000)
IRIS_HOMEไดเรกทอรีสำหรับไฟล์ทั้งหมดของผู้ใช้แต่ละราย: config.json, iris.db, custom-rules.json, audit.log, preferences.json (ค่าเริ่มต้น ~/.iris)
IRIS_DB_PATHพาธฐานข้อมูล SQLite (แทนที่ IRIS_HOME เฉพาะสำหรับฐานข้อมูล)
IRIS_SQLITE_DRIVERไดรเวอร์ SQLite ใดที่ใช้เก็บฐานข้อมูล: native (better-sqlite3 ซึ่งเป็นค่าเริ่มต้น) หรือ node (โมดูล node:sqlite ที่มาพร้อมกับ Node, Node 22.13+) หากไม่ได้ตั้งค่า: ใช้ native และเมื่อโหลดโมดูล native ไม่ได้ (หรือเป็นบิลด์ที่อาจทำให้โปรเซสหยุดทำงานบน Node นี้) Iris จะแจ้งเตือนหนึ่งครั้งและเปลี่ยนไปใช้โมดูลที่มาพร้อมกับ Node
IRIS_SEARCH_BUDGET_MSการค้นหา trace หนึ่งครั้ง (q) อ่านข้อมูลได้นานเท่าใดก่อนตอบกลับพร้อมผลลัพธ์ที่พบจนถึงตอนนั้นและ search.complete: false หน่วยเป็นมิลลิวินาที (50 ถึง 60000, ค่าเริ่มต้น 1000) ระหว่างอ่านข้อมูล การค้นหาจะทำให้คำขออื่นต้องรอด้วย ดังนั้นค่านี้จึงเป็นเวลารอนานที่สุดที่การค้นหาจะทำให้คำขออื่นรอได้ และยังเป็น storage.searchBudgetMs ใน config.json
IRIS_SEARCH_INDEXon (ค่าเริ่มต้น) หรือ off off จะไม่เก็บดัชนีข้อความเต็มรูปแบบของ trace: การเขียนจะเก็บ trace เท่านั้น และการค้นหา trace (q) จะอ่านตัว trace เองภายใน IRIS_SEARCH_BUDGET_MS โดยเรียงจากใหม่ไปเก่า ดังนั้นเมื่อมีข้อมูลจำนวนมาก อาจตอบกลับพร้อมผลลัพธ์เพียงบางส่วน (search.complete: false) เมื่อปิดใช้งาน ดัชนีที่ฐานข้อมูลเก็บไว้จะถูกลบ และเมื่อเปิดใช้งานอีกครั้ง ระบบจะสร้างดัชนีใหม่ในเบื้องหลัง และยังเป็น storage.searchIndex ใน config.json
IRIS_LOG_LEVELระดับบันทึก: debug, info, warn, error
IRIS_DASHBOARDtrue/1/yes/on เปิดใช้แดชบอร์ดเว็บ; false/0/no/off ปิดใช้แดชบอร์ด (และยังแทนที่ dashboard.enabled ใน config.json ด้วย)
IRIS_DASHBOARD_PORTพอร์ตแดชบอร์ด (1-65535, ค่าเริ่มต้น 6920)
IRIS_WEBHOOK_URLปลายทางที่รับ webhook ซึ่งทำงานเมื่อเกิด moment — รวมทับ notify.webhook ใน config.json (docs/webhooks.md)
IRIS_WEBHOOK_SECRETคีย์สำหรับลงนาม webhook (สตริงใดก็ได้ หรือ whsec_ + base64); รูปแบบ iris จะไม่ยอมทำงานหากไม่มีคีย์
IRIS_DASHBOARD_HOSTที่อยู่ bind ของแดชบอร์ด (ค่าเริ่มต้น 127.0.0.1)
IRIS_API_KEYAPI key สำหรับการยืนยันตัวตนผ่าน HTTP จำเป็นต้องใช้เมื่อต้อง bind การขนส่ง HTTP หรือแดชบอร์ดนอก loopback (0.0.0.0, ที่อยู่ LAN, คอนเทนเนอร์): หากไม่มี เซิร์ฟเวอร์จะปฏิเสธการเริ่มทำงาน
IRIS_API_KEY_FILEพาธไปยังไฟล์ที่มี API key หลังตัดช่องว่างหัวท้าย — รูปแบบไฟล์ลับที่ Docker และ Kubernetes เมานต์ไว้ เพื่อไม่ให้คีย์อยู่ในบล็อกตัวแปรสภาพแวดล้อม ตั้งค่านี้หรือ IRIS_API_KEY อย่างใดอย่างหนึ่ง ห้ามตั้งทั้งคู่
IRIS_ALLOW_UNAUTHENTICATEDตั้งเป็น 1 เพื่ออนุญาตให้ bind ที่ไม่ใช่ loopback โดยตั้งใจและไม่มีคีย์ (ยกเลิกการปฏิเสธ; จากนั้นเครือข่ายจะเป็นขอบเขตการป้องกันของคุณ)
IRIS_ALLOWED_ORIGINSรายการอนุญาต origin คั่นด้วยจุลภาค แดชบอร์ด: ส่วนหัว CORS (รองรับ glob เช่น http://localhost:*) การขนส่ง HTTP: รายการอนุญาต Origin ที่ต้องตรงกันทุกประการเพื่อป้องกัน DNS rebinding (ไม่สนใจ glob; origin แบบ loopback ของเซิร์ฟเวอร์เองได้รับอนุญาตเสมอ)
IRIS_MAX_INPUT_ELEMENTSจำนวนสมาชิกอาร์เรย์และคีย์ออบเจ็กต์สูงสุดที่อินพุตหนึ่งรายการมีได้ก่อนตรวจสอบความถูกต้อง (จำนวนเต็มบวก ค่าเริ่มต้น 100000): ใช้กับอาร์กิวเมนต์การเรียกเครื่องมือในทุกการขนส่ง และเนื้อหาคำขอบนพอร์ตแดชบอร์ด (เนื้อหา JSON ของ API และ POST /v1/traces ทั้ง JSON หรือ protobuf) หากการเรียกเครื่องมือเกินค่านี้ จะได้รับผลลัพธ์ข้อผิดพลาด; หากเนื้อหาคำขอเกินค่านี้ 413 ค่าเริ่มต้นรองรับอินพุต JSON ที่ถูกต้องตามกฎหมายทุกกรณีที่วัดได้ แม้แต่กรณีที่ใช้พื้นที่คำขอเต็ม 1 MB เนื้อหา protobuf บน POST /v1/traces มีเพดานของตัวเอง คือหนึ่งสมาชิกต่อทุก 5 ไบต์ของ security.requestSizeLimit (209,716 ที่ 1 MB) หรือใช้ค่านี้หากสูงกว่า ดังนั้นแบตช์ของ exporter ที่อยู่ภายในขนาดคำขอจะไม่ถูกปฏิเสธเพราะมีความหนาแน่นสูง (เนื้อหา exporter จริงที่หนาแน่นที่สุดซึ่งวัดได้มีหนึ่งสมาชิกต่อ 7.5 ไบต์); การเพิ่ม requestSizeLimit สำหรับแบตช์ขนาดใหญ่ขึ้นของ collector จะเพิ่มเพดานนี้ด้วย และยังเป็น security.maxInputElements ใน config.json
IRIS_MAX_TOOL_INPUT_ELEMENTSชื่อของ IRIS_MAX_INPUT_ELEMENTS ก่อนเวอร์ชัน 0.21.0 ซึ่งจะอ่านเมื่อไม่ได้ตั้งชื่อใหม่ (และ security.maxToolInputElements ใน config.json เช่นเดียวกัน)
IRIS_NO_AUTO_LAUNCHตั้งเป็น 1 เพื่อปิดการเปิดแดชบอร์ดอัตโนมัติเมื่อเรียกใช้ครั้งแรก
IRIS_ANTHROPIC_API_KEYจำเป็นสำหรับ evaluate_with_llm_judge + verify_citations ที่ใช้ provider=anthropic
IRIS_OPENAI_API_KEYจำเป็นสำหรับ evaluate_with_llm_judge + verify_citations ที่ใช้ provider=openai
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVALเพดานค่าใช้จ่ายสูงสุดต่อการเรียก LLM judge (ค่าเริ่มต้น 0.25) max_cost_usd ลดค่านี้สำหรับการเรียกหนึ่งครั้งได้ แต่เพิ่มไม่ได้
IRIS_RELEVANCE_JUDGE_MODELID ของโมเดล judge ที่มีการกำหนดราคา (เช่น claude-haiku-4-5) เมื่อตั้งค่านี้พร้อมคีย์ของผู้ให้บริการนั้น answers_the_ask จะสอบถาม LLM judge นี้ในการประเมินทุกครั้งที่มีอินพุต และใช้คำตัดสินด้านความเกี่ยวข้องเป็นเกณฑ์ — หนึ่งครั้งต่อการประเมิน ภายใต้เพดานค่าใช้จ่ายข้างต้นและขีดจำกัดสองรายการด้านล่าง อินพุตและเอาต์พุตของการประเมินแต่ละครั้งจะถูกส่งไปยังผู้ให้บริการโมเดลนั้น (Anthropic หรือ OpenAI) โดยใช้คีย์ของคุณ โดยจะแทนที่ข้อมูลส่วนบุคคลและข้อมูลรับรองที่ตั้งค่า no_pii ก่อน หากไม่ได้ตั้งค่า (ค่าเริ่มต้น) answers_the_ask จะอ่านคำถามตามลักษณะทางภาษาและให้คำแนะนำ โดยไม่มีการส่งข้อมูลใด ๆ (docs/llm-as-judge.md)
IRIS_LLM_JUDGE_DAILY_BUDGET_USDค่าใช้จ่ายรวมสูงสุดที่การเรียก judge ทั้งหมดใช้ได้ต่อวัน UTC ต่อ tenant (ค่าเริ่มต้น 1): relevance judge, evaluate_with_llm_judge และ verify_citations ใช้โควตาร่วมกัน โดยเก็บไว้ในฐานข้อมูล ดังนั้นการรีสตาร์ตจะไม่รีเซ็ตค่า ระบบจะเรียกใช้ได้ก็ต่อเมื่อค่าใช้จ่ายกรณีเลวร้ายที่สุดไม่เกินยอดคงเหลือ; เมื่อเกินแล้ว answers_the_ask จะอ่านคำถามตามลักษณะทางภาษา (judge.withheld: "daily_budget") และเครื่องมือ judge จะตอบกลับเป็น IRIS_BUDGET_EXCEEDED (การอ้างอิง daily_budget_reached) 0 จะหยุดการเรียกทั้งหมด
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USDชื่อของ IRIS_LLM_JUDGE_DAILY_BUDGET_USD ก่อนเวอร์ชัน 0.21.0 ซึ่งใช้จำกัดเฉพาะ relevance judge อ่านค่านี้เมื่อไม่ได้ตั้งชื่อใหม่ และจากนั้นจะใช้จำกัดการเรียก judge ทุกครั้ง; เซิร์ฟเวอร์จะแจ้งเรื่องนี้เมื่อเริ่มทำงาน
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUESTจำนวนครั้งสูงสุดที่คำขอหนึ่งรายการเรียก relevance judge ได้ (ค่าเริ่มต้น 20): แบตช์ OTLP หรือการให้คะแนนใหม่ของ evaluate_runs จะให้ judge ประเมิน trace 20 รายการแรก และอ่านรายการที่เหลือตามลักษณะทางภาษา โดยใช้ judge.withheld: "request_cap"
IRIS_RELEVANCE_JUDGE_REDACTon (ค่าเริ่มต้น): แทนที่ทุกแฟล็ก no_pii (ข้อมูลส่วนบุคคลและข้อมูลรับรอง) ใน span ทั้งหมดของอินพุตและเอาต์พุตด้วยเครื่องหมาย [REDACTED:<kind>#<n>] ก่อนส่งไปยัง relevance judge ส่วน off จะส่งข้อมูลตามเดิม
IRIS_CITATION_ALLOW_FETCHตั้งเป็น 1 เพื่ออนุญาต HTTP ขาออกใน verify_citations (ปิดไว้โดยค่าเริ่มต้น) อาร์กิวเมนต์ของเครื่องมือปิดการทำงานนี้สำหรับการเรียกหนึ่งครั้งได้ แต่เปิดไม่ได้
IRIS_CITATION_DOMAINSรายการอนุญาต hostname คั่นด้วยจุลภาคสำหรับ verify_citations (จับคู่ส่วนท้าย) อาร์กิวเมนต์ของเครื่องมือจำกัดรายการนี้ให้แคบลงได้ แต่เพิ่มรายการไม่ได้
IRIS_CITATION_MAX_COST_USD_TOTALค่าใช้จ่ายสูงสุดที่การเรียก verify_citations หนึ่งครั้งใช้กับการเรียก judge ได้ (ค่าเริ่มต้น 1) max_cost_usd_total ลดค่านี้สำหรับการเรียกหนึ่งครั้งได้ แต่เพิ่มไม่ได้
IRIS_OTEL_ENDPOINTเปิดใช้การส่งออก trace แบบ OTLP/HTTP JSON ที่พยายามส่งให้ดีที่สุดไปยัง URL ของ collector นี้
IRIS_OTEL_SERVICE_NAMEแอตทริบิวต์ทรัพยากร service.name สำหรับการส่งออก OTel (ค่าเริ่มต้น iris-eval)
IRIS_OTEL_HEADERSส่วนหัว k=v คั่นด้วยจุลภาคสำหรับการส่งออก OTel (เช่น authorization=Bearer abc)
IRIS_OTEL_TIMEOUT_MSระยะหมดเวลาต่อการส่งออก (ค่าเริ่มต้น 15000)
RATE_LIMIT_SALTใช้เฉพาะเว็บไซต์ — เพิ่ม salt ให้แฮชที่อยู่ซึ่งระบบจำกัดอัตราการใช้งานของ playground บน iris-eval.com เก็บไว้; เซิร์ฟเวอร์จะไม่อ่านค่านี้

ความปลอดภัย

เมื่อใช้การขนส่ง HTTP Iris จะมีคุณสมบัติดังนี้:

  • การยืนยันตัวตนด้วย API key โดยเปรียบเทียบแบบปลอดภัยต่อการจับเวลา (Bearer สำหรับไคลเอนต์ API; ลงชื่อเข้าใช้แดชบอร์ดผ่านเบราว์เซอร์ด้วย ?key=)
  • จำกัด CORS ให้ใช้ได้เฉพาะ localhost โดยค่าเริ่มต้น
  • จำกัดอัตราการเรียกตามที่อยู่ไคลเอนต์และต่อนาที: 600 คำขอไปยัง API ของแดชบอร์ด (security.rateLimit.api) และ 20 คำขอไปยัง MCP endpoint (security.rateLimit.mcp) โดยทั้งคู่กำหนดไว้ใน config.json; คำขอ MCP ที่เกินขีดจำกัดจะได้รับข้อผิดพลาด JSON-RPC ที่ระบุชื่อคีย์
  • ส่วนหัวความปลอดภัย Helmet
  • ตรวจสอบความถูกต้องของอินพุตทุกเส้นทางด้วย Zod
  • regex ที่ปลอดภัยจาก ReDoS สำหรับกฎ eval แบบกำหนดเอง
  • จำกัดขนาดคำขอไว้ที่ 1MB สำหรับทุกการขนส่ง (security.requestSizeLimit): HTTP ตอบกลับด้วย 413, ส่วน stdio ตอบกลับด้วยข้อผิดพลาด JSON-RPC และเปิดเซสชันไว้
  • จำกัดอินพุตไว้ที่อาร์เรย์และคีย์ออบเจ็กต์รวมกัน 100,000 รายการ โดยนับก่อนตรวจสอบความถูกต้อง (security.maxInputElements): อาร์กิวเมนต์การเรียกเครื่องมือในทุกการขนส่งจะได้รับผลลัพธ์ข้อผิดพลาดเมื่อเกินขีดจำกัด และเนื้อหาคำขอของแดชบอร์ดหรือ OTLP จะได้รับ 413
  • ข้อผิดพลาดในการตรวจสอบความถูกต้องจะแสดงปัญหาไม่เกิน 20 รายการพร้อมจำนวนทั้งหมด (issueCount) เพื่อให้คำตอบมีขนาดเล็กไม่ว่าคำขอจะผิดพลาดเพียงใด
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

เมื่อตั้งค่าคีย์แล้ว ไคลเอนต์ API — ไคลเอนต์ MCP, SDK สำหรับบันทึกข้อมูล, POST /api/v1/traces — จะส่ง Authorization: Bearer <key> หากต้องการเปิดแดชบอร์ดในเบราว์เซอร์ ให้ต่อท้ายคีย์กับ URL ของแดชบอร์ดใดก็ได้เพียงครั้งเดียว http://localhost:6920/?key=<api key>: Iris จะแลกเปลี่ยนคีย์เป็นคุกกี้เซสชัน HttpOnly, SameSite=Lax แล้วเปลี่ยนเส้นทางกลับไปยังหน้าเดิมโดยนำคีย์ออกจากแถบที่อยู่ หน้าเว็บที่เปิดโดยไม่มีเซสชันจะแสดงแบบฟอร์มลงชื่อเข้าใช้ซึ่งทำการแลกเปลี่ยนแบบเดียวกัน คีย์จะไม่ถูกเก็บไว้ในเบราว์เซอร์ และเซสชันจะอยู่ในโปรเซสเซิร์ฟเวอร์เท่านั้น (มีเซสชันที่ใช้งานอยู่ได้สูงสุด 256 รายการ; หากการลงชื่อเข้าใช้พบว่าทุกรายการยังใช้งานอยู่ ระบบจะปฏิเสธแทนการไล่เซสชันใดเซสชันหนึ่งออก)

การใช้งานจริง

หลายคีย์และการหมุนเวียนคีย์โดยไม่สะดุด security.apiKeys ใน config.json เก็บคีย์เพิ่มเติมได้ไม่จำกัดจำนวน โดยแต่ละคีย์มี id และมีอย่างใดอย่างหนึ่งเพียงรายการเดียวจาก keyFile (ไฟล์ที่มีคีย์หลังตัดช่องว่างหัวท้าย) หรือ keyHash (ค่า sha256 แบบ hex ของคีย์ เพื่อให้ไฟล์กำหนดค่าไม่มีข้อมูลลับ — printf %s "$KEY" | openssl dgst -sha256) และอาจมี expiresAt (ISO 8601) ซึ่งเมื่อถึงเวลานั้นคีย์จะหยุดใช้ได้ทันที วิธีหมุนเวียนคีย์: เพิ่มคีย์ใหม่ ย้ายไคลเอนต์ไปใช้คีย์ใหม่ แล้วนำคีย์เก่าออก คีย์ใน config.json และในไฟล์คีย์จะมีผลโดยไม่ต้องรีสตาร์ต (0.20.0): ในแต่ละคำขอ เซิร์ฟเวอร์จะตรวจสอบว่า config.json หรือไฟล์คีย์ที่ระบุมีการเปลี่ยนแปลงหรือไม่ และหากมี จะอ่านคีย์ใหม่ก่อนตอบกลับ การนำคีย์ออกจาก security.apiKeys หรือลบไฟล์คีย์ จะเพิกถอนคีย์นั้นในคำขอถัดไป: คำขอนั้นจะถูกปฏิเสธ และทุกเซสชันเบราว์เซอร์ที่เปิดด้วยคีย์ดังกล่าวจะถูกลงชื่อออก หากอ่าน config.json ไม่ได้ (เช่น เขียนไฟล์ค้างไว้เพียงบางส่วน) ระบบจะปฏิเสธอย่างปลอดภัย และจนกว่าจะแก้ไข จะยอมรับเฉพาะคีย์จาก IRIS_API_KEY หรือ --api-key เท่านั้น ตัวคีย์ใน IRIS_API_KEY หรือ --api-key เอง รวมถึงการเปิดใช้การยืนยันตัวตนหรือไม่ ยังคงเปลี่ยนได้เฉพาะเมื่อรีสตาร์ตเท่านั้น คีย์ทุกตัวใช้ยืนยันตัวตนได้จนกว่าจะถูกนำออกหรือหมดอายุ ทั้งผ่าน Bearer และการลงชื่อเข้าใช้ผ่านเบราว์เซอร์; บันทึกเมื่อเริ่มทำงานจะแสดง ID ของคีย์ security.rateLimit.mcpKeyBy: "apiKey" นับโควตาต่อนาทีของ MCP endpoint แยกตามคีย์แทนที่อยู่ไคลเอนต์ ดังนั้นเอเจนต์หลายตัวที่อยู่หลังที่อยู่เดียวกันจึงได้โควตาของตนเองต่อนาที

หลายไคลเอนต์ --transport http รองรับไคลเอนต์ MCP ได้ไม่จำกัดจำนวนที่ที่อยู่เดียวกัน: แต่ละ initialize จะเปิดเซสชันของตนเองผ่าน engine และ store เดียวกัน โดยรองรับพร้อมกันได้สูงสุด 256 เซสชัน สำหรับ stdio ไคลเอนต์แต่ละตัวจะเริ่มโปรเซสเซิร์ฟเวอร์ของตนเอง และโปรเซสเหล่านั้นใช้ Iris home ร่วมกัน: กฎที่ติดตั้ง ปิดใช้งาน หรือลบผ่านโปรเซสหนึ่งจะมีผลกับโปรเซสอื่นทั้งหมดภายใน 20 ms; ป้ายกำกับที่เขียนผ่านโปรเซสหนึ่งจะถูกโปรเซสอื่นอ่านได้ทันที และหากสองโปรเซสเปลี่ยนกฎพร้อมกัน จะไม่มีการเปลี่ยนแปลงใดสูญหาย Iris ปฏิเสธที่จะเริ่มทำงาน เมื่อผูก HTTP transport หรือแดชบอร์ดไว้กับที่อยู่นอก loopback — 0.0.0.0, ที่อยู่ LAN, คอนเทนเนอร์ — โดยไม่มี API key และแจ้งเหตุผลในประโยคเดียวที่ระบุ IRIS_API_KEY ซึ่งรวมถึงการใช้ docker run ของอิมเมจโดยไม่ระบุค่า ซึ่งจะผูกกับ 0.0.0.0 ภายในคอนเทนเนอร์ เพราะไม่สามารถเข้าถึง loopback ผ่านพอร์ตที่เผยแพร่ได้ การใช้ loopback โดยไม่มี key ยังคงทำงานได้ (พร้อมคำเตือนบน HTTP transport): ขอบเขตของเครื่องเป็นตัวควบคุมการเปิดเผยข้อมูลในกรณีนั้น

# 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

เปิดให้เข้าถึงโดยตั้งใจบนเซิร์ฟเวอร์ที่มี key: GET /health บน transport และ GET /api/v1/health บนแดชบอร์ดตอบกลับได้โดยไม่ต้องใช้ key และไม่อยู่ภายใต้ขีดจำกัดอัตราใด ๆ โดยใช้รูปแบบเดียวกัน ได้แก่ สถานะ เวอร์ชัน เวลาทำงาน ไดรเวอร์ SQLite, checks สำหรับพื้นที่จัดเก็บ ไฟล์กฎที่นำไปใช้และ migrations (ที่นำไปใช้เทียบกับ known) สถานะของดัชนีค้นหา (search: พร้อมใช้งาน หรือความคืบหน้าการสร้างเป็นสัดส่วนของ traces) และมี judge key หรือไม่ — ไม่แสดง key ไม่แสดง trace และไม่แสดงจำนวน trace status จะเป็น ok ก็ต่อเมื่อการตรวจสอบทุกอย่างผ่านเท่านั้น มิฉะนั้นจะเป็น degraded พร้อม HTTP 503 ซึ่ง HEALTHCHECK ของอิมเมจ Docker ใช้อ่าน ทุกอย่างอื่นต้องใช้ Authorization: Bearer <key> หรือเซสชันเบราว์เซอร์ การเก็บรักษาข้อมูลทำงานบนทุกเซิร์ฟเวอร์: traces และ evaluations ที่เก่ากว่า retention.days (ค่าเริ่มต้น 30) จะถูกลบเมื่อเริ่มต้น หลังจากเซิร์ฟเวอร์เริ่มตอบสนองแล้ว และทุก ๆ retention.sweepIntervalHours โดยแบ่งทำเป็นช่วงสั้น ๆ เพื่อไม่ให้คำขอต้องรอนาน --self-test แสดงนโยบายของการติดตั้งนี้ และ iris://capabilities / GET /api/v1/capabilities ส่งนโยบายนี้ไปในรูปแบบ retention

webhook จะทำงานเมื่อเกิดเหตุการณ์ (0.16.0): notify.webhook ใน config.json (หรือ IRIS_WEBHOOK_URL และ IRIS_WEBHOOK_SECRET) ใช้ระบุปลายทางรับข้อมูล และ Iris จะส่งข้อความที่ลงลายเซ็นหนึ่งครั้งเมื่อ verdict ไม่ผ่าน การตรวจจับระดับ critical ยับยั้งผลลัพธ์ ค่าใช้จ่ายเป็นค่าผิดปกติ อัตราความล้มเหลวของกฎเปลี่ยนแปลง หรือมีการตอบ case ทั้งสองแบบเป็นครั้งแรก — ส่งเฉพาะ ID, verdict, กฎ และตัวเลข ไม่ส่งข้อความของ agent ลงลายเซ็นพร้อมกันตามวิธีของ Standard Webhooks และ GitHub ส่งซ้ำโดยหน่วงเวลาแบบ backoff จำกัดความถี่แยกตาม agent และกฎ โดยไม่รบกวนการประเมินผล มีรูปแบบข้อความสำหรับ Slack และ Discord มาให้ในตัว docs/webhooks.md

ข้อมูลของคุณบนดิสก์

ทุกอย่างที่ Iris จัดเก็บจะอยู่ในโฟลเดอร์หลักของ Iris (~/.iris หรือ IRIS_HOME) iris.db เก็บ input และ output ของทุก trace ไว้แบบ ตรงตามต้นฉบับ — รวมถึงข้อความใด ๆ ที่ no_pii จะนำไปแจ้งเตือนต่อ การตรวจจับจะไม่ปกปิดข้อมูล เว้นแต่คุณจะสั่งให้ทำ: storage.redact: "critical_spans" ใน config.json จัดเก็บผลลัพธ์ของแต่ละ evaluation โดยแทนช่วงข้อความที่ตัวตรวจจับระดับ critical แจ้งเตือนด้วย [REDACTED:<pattern>] (ปิดไว้โดยค่าเริ่มต้น; offset ของหลักฐานยังคงอ้างอิงข้อความที่ผู้เรียกเห็น) storage.synchronous กำหนดเวลาที่การเขียนข้อมูลจะลงดิสก์: normal (ค่าเริ่มต้น) จะ sync write-ahead log ที่แต่ละ checkpoint ดังนั้นหาก Iris ขัดข้องจะไม่สูญเสียข้อมูลและไฟล์จะไม่เสียหาย แต่ไฟดับหรือระบบปฏิบัติการขัดข้องอาจทำให้การเขียนข้อมูลนับจากการ sync ครั้งล่าสุดถูกย้อนกลับได้ ส่วน full จะ sync ทุก commit และเก็บข้อมูลไว้แม้เกิดเหตุทั้งสองแบบ โดยเพิ่มเวลาต่อการเขียนประมาณ 1.5 ms เมื่อเริ่มต้น และทุก ๆ retention.sweepIntervalHours (ค่าเริ่มต้น 24; 0 ปิดตัวจับเวลา) หลังจากนั้น traces และ evaluations ที่เก่ากว่า retention.days (ค่าเริ่มต้น 30; 0 ปิดการทำงาน; ตั้งค่าใน config.json) จะถูกลบและ write-ahead log จะถูก checkpoint มีข้อมูลหนึ่งอย่างที่เก็บไว้นานกว่าช่วงเวลานี้: baseline run ที่ปักหมุดไว้ พร้อม evaluations ของมัน เพราะเป็นข้อมูลที่ใช้เปรียบเทียบกับ run ถัดไปทุกครั้ง การกวาดข้อมูลแต่ละครั้งที่เก็บข้อมูลบางส่วนไว้จะแจ้งใน log พร้อม run และจำนวนข้อมูล; ยกเลิกการปักหมุด run แล้วการกวาดครั้งถัดไปจะลบข้อมูลนั้น Dataset cases และ labels ไม่ใช่ traces หรือ evaluations จึงไม่ถูกกวาด การลบ trace — ด้วย delete_trace หรือการกวาดข้อมูล — จะลบข้อความของทุก evaluation ที่เชื่อมโยงกับ trace นั้น (ผลลัพธ์ ข้อความที่คาดหวัง และข้อความของกฎ) และประทับ erased_at; verdict, scores และ offset ของหลักฐานจะยังคงอยู่ การลบแต่ละครั้งจะ checkpoint write-ahead log ก่อนส่งคืน ดังนั้นข้อความที่ลบแล้วจะไม่เหลือให้อ่านได้ใน iris.db หรือ iris.db-wal (หากมีการค้นหากำลังอ่านไฟล์อยู่ในขณะนั้น หรือมีโปรเซสอื่นกำลังอ่านหรือเขียนไฟล์ การลบจะส่งคืนโดยไม่รอ และข้อความจะออกจากไฟล์ทันทีที่การทำงานเสร็จสิ้น) หากต้องการลบทุกอย่างทันที ให้หยุดเซิร์ฟเวอร์แล้วเรียกใช้ --purge: คำสั่งนี้จะลบ trace, span และ evaluation ที่จัดเก็บไว้ทั้งหมด บีบอัดฐานข้อมูล และตัด write-ahead log ให้สั้นลงเพื่อให้ข้อความหายไปจากดิสก์ โดยเก็บกฎที่นำไปใช้แล้ว audit log และการตั้งค่าไว้ ก่อนที่ release จะนำ migration ไปใช้กับ iris.db ที่มีอยู่ จะคัดลอกไฟล์ไปไว้ข้าง ๆ (iris.db.<from>-to-<to>.<time>.bak, เจ้าของเท่านั้นที่เข้าถึงได้; เก็บสามไฟล์ล่าสุดไว้; การย้อนกลับไปใช้เวอร์ชันก่อนหน้า): สำเนานี้เก็บ traces ไว้ตามเดิม ดังนั้นการกวาดข้อมูลจะลบรายการที่เก่ากว่า retention.days และ --purge จะลบทั้งหมด เซิร์ฟเวอร์จะคัดลอกไฟล์และทำ migrations หลังจากตอบกลับ client แล้ว โดยทำงานบน thread ของตัวเอง: การเรียกใช้ tool, การอ่าน resource และคำขอ HTTP ที่เข้ามาระหว่างนั้นจะรอได้ไม่เกิน 30 s ต่อรายการ จากนั้นจะถูกปฏิเสธพร้อมประโยคแจ้งว่าเซิร์ฟเวอร์กำลังทำอะไรอยู่ (IRIS_STORAGE_ERROR, ลองใหม่ได้; HTTP 503 พร้อม Retry-After) Health จะตอบกลับตลอดเวลาและแจ้งว่ากำลังอัปเกรดอะไรอยู่ ตั้งแต่ 0.19.0 ที่มี 100,000 traces ซึ่งแต่ละรายการเป็น agent loop การคัดลอกและ migrations ใช้เวลาประมาณ 6 s iris-eval ingest, --purge และ --self-test ยังคงอัปเกรดก่อนทำสิ่งอื่นใด

Iris ไม่เข้ารหัสข้อมูลขณะจัดเก็บ iris.db และไฟล์ write-ahead log จะถูกสร้างโดยให้สิทธิ์เฉพาะเจ้าของ (mode 600) และโฟลเดอร์หลักของ Iris จะถูกสร้างด้วย mode 700 (บน Windows จะใช้ file ACL แทน) ฐานข้อมูลไม่จัดเก็บ key ของผู้ให้บริการ LLM: IRIS_ANTHROPIC_API_KEY และ IRIS_OPENAI_API_KEY จะอ่านจาก environment และไม่เขียนลงดิสก์ แต่ฐานข้อมูลจัดเก็บอินพุตและเอาต์พุตของ trace ตามต้นฉบับ ดังนั้นควรเก็บโฟลเดอร์หลักของ Iris ไว้บนดิสก์หรือ volume ที่เข้ารหัส (FileVault, BitLocker, LUKS หรือ cloud volume ที่เข้ารหัสสำหรับ mount /data ของอิมเมจ Docker)

การส่งออก — ด้วยปุ่ม Export บนหน้า Traces และ Evaluations ของแดชบอร์ด, GET /api/v1/traces/export และ /api/v1/evaluations/export หรือ iris-eval export — จะส่งข้อความที่จัดเก็บไว้ออกไปตามเดิม เหมือนกับที่แดชบอร์ดแสดง: อินพุตและเอาต์พุตของ trace ตามต้นฉบับ และเอาต์พุตของ evaluation ที่ใช้ storage.redact แล้ว ให้ดูแลไฟล์ที่ส่งออกเช่นเดียวกับฐานข้อมูลต้นทาง

การแก้ไขปัญหา

ขั้นแรก: เรียกใช้การทดสอบตัวเอง

npx @iris-eval/mcp-server --self-test

การทดสอบนี้ตรวจสอบพื้นที่จัดเก็บ evals แบบกำหนดผลแน่นอน และแดชบอร์ดในโฟลเดอร์ชั่วคราวที่แยกต่างหาก พร้อมพิมพ์ verdict ของแต่ละขั้นตอน — ข้อความแสดงความล้มเหลวจะระบุขั้นตอนที่มีปัญหา รหัสออก 0 หมายความว่าการติดตั้งทำงานปกติ

Iris เริ่มทำงานไม่ได้ / ERR_MODULE_NOT_FOUND

คุณอาจมีเวอร์ชันเก่าที่แคชไว้ ล้างแคชของ npx แล้วลองอีกครั้ง:

npx --yes @iris-eval/mcp-server@latest

หรือจะติดตั้งแบบ global เพื่อหลีกเลี่ยงปัญหาแคชทั้งหมดก็ได้:

npm install -g @iris-eval/mcp-server@latest

npm install --ignore-scripts ทำให้ SQLite binding ใช้งานไม่ได้

Iris จัดเก็บ traces ด้วย better-sqlite3 ซึ่งเป็น native module ที่ดาวน์โหลดหรือคอมไพล์ binding ในสคริปต์ติดตั้ง หากข้ามสคริปต์นั้นไป — ด้วย --ignore-scripts บน command line, ignore-scripts=true ใน .npmrc (พบได้บ่อยในเครื่องขององค์กร) หรือ registry mirror ที่ตัด postinstall ออก — การเริ่มต้นจะล้มเหลวพร้อมข้อความยาว ๆ ว่า "Could not locate the bindings file" ซึ่งแสดงรายการ path ที่ลองค้นหาหลายสิบรายการ ให้ rebuild เฉพาะโมดูลนั้น:

npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3

ไม่มี tools แสดงใน Claude Code

MCP tools จะโหลดเมื่อเริ่มเซสชันเท่านั้น หลังเพิ่ม iris-eval แล้ว ให้เริ่มเซสชันใหม่ด้วย /clear หรือเปิด terminal ใหม่

ตรวจสอบเวอร์ชัน

npx @iris-eval/mcp-server --version

บรรทัดแรกของ startup log ก็แสดงเวอร์ชันนี้เช่นกัน (Starting Iris MCP server vX.Y.Z) และ --self-test จะแสดงเวอร์ชันในสรุป หากติดตั้งแบบ global ให้ใช้ npm ls -g @iris-eval/mcp-server เพื่อดูเวอร์ชันที่ติดตั้งไว้

การอัปเดต

MCP client ทุกตัวในเครื่องเดียวกันใช้ฐานข้อมูลร่วมกันหนึ่งชุด คือ ~/.iris/iris.db และ install จะตรึง client แต่ละตัวไว้กับ release ที่เขียน config ของมัน เมื่อ release เปลี่ยน schema ของฐานข้อมูล โปรเซสแรกของ release นั้นที่เปิดไฟล์จะอัปเกรดไฟล์ และหลังจากนั้น client ที่ยังตรึงอยู่กับ release เก่าจะปฏิเสธการเริ่มทำงาน ดังนั้นให้อัปเดต client ทุกตัวในขั้นตอนเดียว ก่อนหรือทันทีหลังอัปเกรด:

npx -y @iris-eval/mcp-server@latest install --upgrade

คำสั่งนี้ค้นหา config ของ client ทุกตัวในเครื่องนี้ที่เรียกใช้ Iris และเปลี่ยน pin ของแต่ละตัวไปยัง release นั้น (โดยเก็บสิ่งที่คุณเพิ่มไว้ใน entry เช่น --dashboard หรือบล็อก env) ไม่เปลี่ยน pin ที่ชี้ไปยัง release ที่ใหม่กว่า และไม่เปลี่ยน entry ที่เรียกใช้สิ่งอื่นนอกเหนือจาก npm package พร้อมแสดงรายการสิ่งที่ทำไปแล้ว ให้เริ่ม client ที่ระบุใหม่ install --list แสดงว่า client แต่ละตัวเรียกใช้ Iris เวอร์ชันใด

การติดตั้งสองแบบอยู่นอกไฟล์เหล่านั้น: Claude Desktop extension (iris-eval.mcpb) จะเปลี่ยนเมื่อคุณเปิด bundle ที่ใหม่กว่า ส่วน Claude Code plugins ให้ใช้ claude plugin marketplace update iris-eval แล้วตามด้วย claude plugin update iris-eval@iris-eval (และ claude plugin update iris-eval-capture@iris-eval สำหรับ capture plugin)

อัปเกรดจาก 0.19.x เป็น 0.20.0 0.20.0 เพิ่มดัชนีค้นหาและส่วนเพิ่มเติมอื่น ๆ ลงในฐานข้อมูล (migrations 015 เป็นต้นไป) เมื่อโปรเซส 0.20.0 ใด ๆ เปิด ~/.iris/iris.db แล้ว (Claude Desktop extension, npx iris-eval หรือ npx @iris-eval/mcp-server ที่ไม่ระบุเวอร์ชัน) client ที่ตรึงอยู่กับ 0.19.x จะหยุดทำงานพร้อม This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, … ข้อความนี้มาจาก 0.19.x และไม่สามารถเปลี่ยนแปลงได้ วิธีแก้คือใช้คำสั่งด้านบน ก่อนอัปเกรด 0.20.0 จะคัดลอกไฟล์ไปไว้ข้าง ๆ จึงสามารถย้อนกลับได้เช่นกัน (ดูด้านล่าง)

การเริ่มทำงานที่อัปเกรดฐานข้อมูลจะแสดงสิ่งที่ทำไปแล้วทาง stderr: สำเนาที่สร้างไว้ release เก่าที่ไม่สามารถเปิดไฟล์ได้อีกต่อไป และ client ใดในเครื่องนี้ที่ยังตรึงอยู่กับ release เหล่านั้น พร้อมคำสั่ง --self-test อ่านฐานข้อมูลโดยไม่เปลี่ยนแปลง และแจ้งข้อมูลเดียวกันก่อนที่คุณจะเริ่มทำสิ่งใด

หากติดตั้งแบบ global ให้ใช้ npm update -g @iris-eval/mcp-server แล้วตามด้วย iris-eval install --upgrade

การย้อนกลับไปใช้เวอร์ชันก่อนหน้า

release ที่อัปเกรดฐานข้อมูลจะคัดลอกไฟล์ไว้ก่อน โดยวางไว้ข้าง ๆ: iris.db.<from>-to-<to>.<time>.bak ในโฟลเดอร์หลักของ Iris (<from> คือ release ที่เปลี่ยน schema ของไฟล์ครั้งล่าสุด ส่วน <to> คือ release ที่อัปเกรดไฟล์; บรรทัด startup จะแสดง path ที่แน่นอน) หากต้องการย้อนกลับ:

  1. หยุด MCP client ทุกตัวและโปรเซส Iris อื่น ๆ ที่ใช้ฐานข้อมูล
  2. เก็บไฟล์ที่อัปเกรดไว้ เผื่อกลับมาใช้อีก: เปลี่ยนชื่อ iris.db เป็น iris.db.upgraded และลบ iris.db-wal กับ iris.db-shm หากมี
  3. คัดลอกไฟล์สำรองไปยัง iris.db: cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db
  4. ตรึง client ทุกตัวกลับไปยัง release เก่า: ใช้ npx -y @iris-eval/mcp-server@0.19.0 install <client> กับแต่ละตัว (install --upgrade จะไม่เปลี่ยน client กลับไปใช้เวอร์ชันเก่า)

Traces ที่จัดเก็บหลังการอัปเกรดจะอยู่ใน iris.db.upgraded ไม่ใช่ในไฟล์สำรอง หากไม่มีการสร้างสำเนา (บรรทัด startup จะระบุเหตุผล เช่น ดิสก์เต็ม) release เก่าจะเปิดไฟล์ที่อัปเกรดแล้วไม่ได้ และวิธีดำเนินการต่อคือ install --upgrade

ไดรเวอร์พื้นที่จัดเก็บ

การติดตั้งยังสำเร็จได้บนแพลตฟอร์มที่ไม่มี better-sqlite3 ที่สร้างไว้ล่วงหน้า better-sqlite3 เป็น optional dependency: เมื่อ npm ดาวน์โหลด binary ที่สร้างไว้ล่วงหน้าสำหรับ Node และแพลตฟอร์มของคุณไม่ได้ และคอมไพล์เองก็ไม่ได้ (การคอมไพล์ต้องใช้ Python และ C++ toolchain — บน Windows คือ Visual Studio C++ build tools) npm จะแสดงข้อผิดพลาดจากการ build ข้ามโมดูลนั้น แล้วติดตั้งต่อจนเสร็จ จากนั้น Iris จะทำงานด้วย SQLite ที่มีมาใน Node และแจ้งให้ทราบ: startup จะแสดงหนึ่งบรรทัดทาง stderr เพื่อระบุสาเหตุ และ --self-test จะแสดง driver node: better-sqlite3 is not installed … หากต้องการใช้ native driver อีกครั้ง ให้ติดตั้งในสภาพแวดล้อมที่มี prebuild หรือ toolchain (npm install better-sqlite3 ในโปรเจกต์; หากติดตั้งแบบ global ให้ติดตั้ง Iris อีกครั้งด้วย npm install -g @iris-eval/mcp-server เมื่อมี toolchain พร้อมใช้งาน) CI ติดตั้ง server ที่แพ็กไว้โดยบังคับให้ native build ล้มเหลวทุกครั้งที่มีการเปลี่ยนแปลง และกำหนดให้การติดตั้งต้องเสร็จสมบูรณ์ รวมถึง self-test ต้องจัดเก็บและอ่าน trace ด้วย built-in ได้ Iris เก็บทุกอย่างไว้ในไฟล์ SQLite ไฟล์เดียว ซึ่งเปิดโดย better-sqlite3 — ส่วนเสริมแบบ native ที่ดาวน์โหลดหรือคอมไพล์ให้เหมาะกับ Node และแพลตฟอร์มของคุณ เมื่อโหลดโมดูลนั้นไม่ได้ Iris จะเปลี่ยนไปใช้ SQLite ที่มาพร้อมกับ Node (node:sqlite, Node 22.13 ขึ้นไป) พร้อมแสดงคำเตือนหนึ่งครั้งบน stderr ดังนั้นการไม่มี prebuild จึงทำให้เริ่มทำงานช้าลง ไม่ใช่เริ่มทำงานไม่ได้ Iris ทำเช่นเดียวกันก่อนโหลด better-sqlite3 ที่คอมไพล์บนเครื่องของคุณโดยใช้ headers ของ Node 24.19 ขึ้นไป แล้วนำไปรันบน Node 24.19 ถึง 24.21: ในเวอร์ชันเหล่านั้น ไบนารีดังกล่าวจะทำให้ทั้งโปรเซสหยุดทำงานทันทีที่มีการคืนหน่วยความจำของ statement เป็นครั้งแรก (Assertion failed: (env) != nullptr, nodejs/node#65446). Node 24.22.0 มีการแก้ไขปัญหานี้แล้ว และ Iris จะโหลดไบนารีในเวอร์ชันนั้น npm rebuild better-sqlite3 แทนที่ด้วยไบนารีที่สร้างไว้ล่วงหน้า ซึ่งปลอดภัยในทุกเวอร์ชัน IRIS_SQLITE_DRIVER=node เลือกใช้ตัวที่มาพร้อมกับ Node โดยตั้งใจ ส่วน native จะห้ามใช้ตัวสำรอง ตัวที่มาพร้อมกับ Node จะเปิดใช้งานโดยปิดการโหลดส่วนขยายและปิด trusted_schema; Node จะแสดงบรรทัด ExperimentalWarning: SQLite is an experimental feature ของตัวเองบน stderr เมื่อโหลด และ Iris จะไม่ปิดบรรทัดนี้ --self-test และ GET /health ใช้ระบุไดรเวอร์ที่กำลังใช้งาน ตัวเลขทั้งหมดในหน้าผลการทดสอบวัดจากไดรเวอร์แบบ native และชุดทดสอบจะทำงานกับไดรเวอร์ทั้งสองแบบใน CI

เวอร์ชัน Node.js

Iris ต้องใช้ Node.js 22.13 ขึ้นไป Node 20 สิ้นสุดระยะการสนับสนุนเมื่อ 2026-04-30 และไม่รองรับ ส่วน Node 18 สิ้นสุดระยะการสนับสนุนในเดือนเมษายน 2025

กำหนดเวอร์ชันขั้นต่ำเป็น 22.13 แทนที่จะเป็น 22.0 เพราะ 22.13.0 เป็นรุ่นแรกที่มาพร้อมกับ node:sqlite ทำให้เป็นเวอร์ชันแรกที่การติดตั้ง Iris ที่รองรับทุกแบบมีไดรเวอร์จัดเก็บข้อมูล ตัวที่สอง: เมื่อโหลดส่วนเสริมแบบ native better-sqlite3 ไม่ได้ Iris จะเปลี่ยนไปใช้ SQLite ที่มาพร้อมกับ Node แทนที่จะเริ่มทำงานไม่สำเร็จ ก่อน 22.13 — และตลอดอายุการใช้งานของ Node 20 — มีไดรเวอร์เพียงตัวเดียวมาโดยตลอด และการไม่มี prebuild ก็ทำให้เริ่มทำงานไม่ได้

node --version  # Must be v22.13.0 or newer

Windows: ไม่จำเป็นต้องใช้ cmd /c

/doctor ของ Claude Code อาจแนะนำให้ครอบ npx ด้วย cmd /c ซึ่งไม่จำเป็นและทำให้เกิดปัญหาในการแยกวิเคราะห์พาธ ใช้ 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"

หาก Iris มีประโยชน์กับคุณ ลองกดดาวให้ repo — จะช่วยให้คนอื่นค้นพบได้ง่ายขึ้น

Star on GitHub

เผยแพร่ภายใต้สัญญาอนุญาต MIT