MEVA

의료 증거 검증 에이전트

기능: MEVA는 AI가 생성한 의료 기록 주장이 검색된 합성 FHIR 증거에 근거하는지 결정론적(비-AI) 검증기를 사용하여 평가합니다 — 진단도, 치료 조언도, 실제 환자 데이터도 없습니다.

🧪 라이브 샌드박스

브라우저에서 MEVA를 사용해 보세요 — Ollama, API 키, 설치가 필요 없습니다.

▶ 라이브 샌드박스 열기

• 합성 데이터만 사용 — Synthea로 생성된 21명의 가상 환자

• 결정론적 검증기 — 모든 결과는 모델의 의견이 아닌 순수 Python 증거 매칭에서 나옵니다

• 공개 샌드박스에서 AI 모델은 실행되지 않습니다 — 직접 주장을 만들면 MEVA가 실제 기록된(합성) 데이터와 대조하여 확인합니다

라이브 샌드박스 사용해 보기 · 빠른 시작 · 벤치마크 방법론 · 기여하기

MEVA는 의료 챗봇, 진단 AI, 임상 의사결정 지원 도구, 치료 권장 시스템 또는 의료 기기가 아닙니다. 임상적으로 검증되지 않았습니다. 모든 환자 데이터는 100% 합성입니다. 전체 내용은 아래 범위 및 안전과 docs/safety-and-scope.md를 참조하십시오.

Related MCP server: MediLinkAI

MEVA 작동 살펴보기

호스팅된 라이브 샌드박스의 스크린샷 — 합성 데이터만 사용하며, 의료 조언이 아니고, 호스팅된 샌드박스에서는 AI 모델이 실행되지 않습니다 (모든 결과는 모델의 의견이 아닌 MEVA의 결정론적 검증기에서 나옵니다).

안내 모드

안내 모드 — 간단한 일반 영어 워크플로를 사용하여 가상 환자를 선택하고 주장을 검증합니다.

증거 기반 검증

MEVA는 주장을 기록된 합성 FHIR 증거와 대조하여 SUPPORTED, CONTRADICTED, UNSUPPORTED 또는 UNVERIFIABLE을 반환합니다.

고급 모드

고급 모드 — 개발자, 연구자, 기여자를 위한 기술 증거 탐색기 및 구조화된 주장 컨트롤.

MEVA가 존재하는 이유

로컬 AI 에이전트는 도구를 호출하고 실제 데이터를 검색한 후 구조화된 “답변”을 생성할 수 있지만, 그 구조화된 답변이 에이전트가 검색한 증거와 실제로 일치하도록 강제하는 것은 없습니다. MEVA는 모델이 자신의 정확성에 대해 스스로 보고하는 것을 절대 신뢰하지 않는 검증기를 사용하여 그 격차를 직접 측정합니다.

아키텍처

flowchart TD
    A[Synthetic Synthea FHIR data] --> B[MEVA FHIR layer]
    B --> C[MCP tools]
    C --> D[Local AI model - via Ollama]
    D --> E[Natural-language answer]
    E --> F[Claim extraction]
    F --> G[Deterministic evidence verifier]
    G --> H[Benchmark / report]

MEVA는 두 가지 평가 모드를 지원하며, 각각 별도로 보고되고 하나의 점수로 결합되지 않습니다 (docs/decoupled-evaluation.md 참조):

• END_TO_END — 테스트 대상 모델이 질문에 답하고 동시에 자신의 답변을 MEVA의 구조화된 MedicalClaim 스키마로 한 번에 인코딩합니다.

• DECOUPLED — 테스트 대상 모델은 산문으로만 답변합니다. 별도의 고정 추출기 모델이 저장된 산문을 구조화된 주장으로 변환하며, 동일한 방식으로 검증됩니다. 이는 “모델이 올바른 답을 알았는가”와 “모델이 JSON을 올바르게 형식화했는가”를 분리합니다.

두 모드 모두에서 최종 검증 단계(주장을 실제 증거와 대조하는 작업)는 항상 순수하고 결정론적인 Python입니다. 어떤 LLM도 자신(또는 다른 모델)의 정확성을 판단하지 않습니다.

빠른 시작

git clone https://github.com/Tanz2024/meva-health-ai
cd meva-health-ai

python3 -m venv .venv
source .venv/bin/activate

pip install -e .

pytest

MEVA는 이 저장소의 클론 복사본 내에서 실행되도록 설계되었습니다 (위와 같이 — git clone 후 편집 가능한 설치). 다른 곳에서 설치한 독립 패키지가 아닙니다. 합성 FHIR 픽스처(data/synthetic/synthea/)와 벤치마크 정의(benchmarks/)는 저장소 상대 경로에서 읽으며, 설치 가능한 패키지 데이터로 번들되지 않습니다 — 저장소 체크아웃 외부에서 빌드된 wheel/sdist를 pip install하면 환자 데이터를 사용할 수 없습니다. 이것은 현재의 의도된 범위입니다(배포 라이브러리가 아닌 연구/엔지니어링 저장소) — 향후 변경되면 docs/publishing-checklist.md를 참조하십시오.

이것은 전체 오프라인 테스트 스위트를 실행합니다 (AI 모델 필요 없음 — AI 없이 실행되는 기능 참조).

선택 사항 — 로컬 AI:

ollama pull qwen3:4b
python3 examples/verify_local.py

더 많은 실행 가능한 스크립트는 examples/를 참조하고, MEVA가 Ollama와 통신하는 방법은 docs/local-ai.md를 참조하십시오.

AI 없이 실행되는 기능 (Ollama 불필요)

MEVA의 대부분은 AI 모델 없이 작동합니다:

• FHIR 파싱 (src/meva/fhir/)

• 결정론적 증거 검증 (src/meva/verification/)

• 벤치마크 데이터셋 로딩 및 검증 (meva.benchmark.validator)

• 전체 오프라인 테스트 스위트 (pytest)

• 검증기 도전 예제 (examples/verify_contradiction_demo.py) — 실제 모델 없이 손으로 작성한 잘못된 주장으로 MEVA 자체 검증 로직을 테스트합니다

Ollama는 실제 로컬 모델 추론을 실행할 때만 필요합니다 (examples/ask_local.py, examples/chat_local.py) 또는 모델 지원 주장 추출(examples/run_decoupled_pilot.py, run_decoupled_full.py, run_extractor_fidelity.py).

합성 데이터

MEVA의 공개 환자 픽스처(data/synthetic/synthea/patient-01.json부터 patient-21.json까지)는 이 프로젝트가 공식 Apache-2.0 라이선스 Synthea 생성기(태그 v3.4.0에 고정)를 사용하여 로컬에서 생성하며, 고정되고 문서화된 재현 가능한 시드를 사용합니다. 실제 환자 데이터는 어디에도 포함되지 않습니다. 전체 생성 세부 정보(정확한 명령, 시드, 파일별 SHA-256 해시)는 data/synthetic/synthea/PROVENANCE.md에 있습니다. 전체 내용은 docs/synthetic-data.md를 참조하십시오. 여기에는 이전의 18명의 환자 세트(Stage 8A까지 사용)가 교체된 이유도 포함됩니다 — 그 이전 세트는 라이선스가 명시되지 않은 저장소에서 복사되었으며 더 이상 공개 데이터셋의 일부가 아닙니다 (docs/historical-sample-data-provenance.md 참조).

벤치마크 결과

MEVA에는 기록된 두 개의 벤치마크 데이터셋이 있으며, 혼동해서는 안 됩니다:

공개 재현 가능 데이터셋: benchmark v0.4 — 위의 로컬 생성 Apache-2.0 픽스처로만 구성됨 (53개 사례, 16명의 고유 환자; benchmarks/v0.4/manifest.json 참조). v0.4 모델 비교 결과는 보류 중입니다 — 아직 v0.4에 대해 qwen3:4b/llama3.2:3b 실행이 수행되지 않았습니다.

역사적 개발 결과: benchmark v0.3 — 전체 qwen3:4b 대 llama3.2:3b 결과는 아래에 있습니다. 이것은 현재 제거된 이전 환자 세트(위 참조)를 기준으로 측정되었습니다 — 방법론과 발견 사항에 대한 유효한 역사적 개발 기록으로 남아 있지만, 현재 공개 v0.4 데이터셋에 대한 결과는 아니며 둘을 직접 비교해서는 안 됩니다. 전체 보고서: docs/baseline-results-v0.3.md (아래 숫자는 수정된 Stage 7C2.1 검증 가능 커버리지 공식을 사용합니다 — 수정 내역은 해당 문서를 참조하십시오. 원래 수정 전 숫자도 숨기지 않고 공개되어 있습니다).

승자는 선언되지 않습니다. grounding 점수는 검증 가능한 커버리지와 함께 읽으십시오 — 확인 가능한 주장이 매우 적은 상태에서 계산된 높은 grounding 점수는 실제보다 좋아 보입니다.

검색 + END_TO_END 구조화 출력 메트릭 (v0.3, 역사적)

DECOUPLED 평가 (v0.3, 역사적; 별도의 고정 qwen3:4b 추출기)

DECOUPLED 평가는 두 모델의 저장된 답변(자신의 답변 포함)에 대해 qwen3:4b를 고정 주장 추출기로 사용합니다 — 이는 잠재적인 추출기 특정 편향을 도입하며, docs/decoupled-evaluation.md에 명시적으로 문서화되어 있습니다. END_TO_END와 DECOUPLED는 서로 다른 질문에 답하며 절대 “모델이 더 나아졌다”로 읽어서는 안 됩니다.

추출기 검증 — 추출기는 완벽하지 않습니다

위의 ~99% DECOUPLED 커버리지 수치를 “99% 추출 정확도”로 읽지 마십시오. 커버리지는 검증기가 추출기 출력의 얼마나 많은 부분을 확인할 수 있었는지를 측정합니다. 여기의 홀드아웃 수치는 해당 출력이 원본 답변이 말한 내용과 실제로 일치하는지 측정합니다.

관찰 범주 결과

두 모델 모두 관찰 범주 질문에서 비정상적으로 낮은 점수를 받았습니다: qwen3:4b 20%, llama3.2:3b 0% grounding (각 10개 사례). Stage 7D2.2는 MEVA의 실제 FHIR 데이터 및 도구 계층에 대해 모든 관찰 사례를 독립적으로 감사했으며, 이러한 결과를 무효화하는 인프라 또는 평가 버그가 없음을 발견했습니다 — 20개의 모델-사례 쌍 중 18개는 진짜 모델 grounding 오류입니다. 전체 감사: docs/observation-audit.md. 이것은 벤치마크 동작을 설명하는 것이지 임상 성능이 아닙니다.

MEVA 사용해 보기 (결정론적 검증 전용, AI 모델 불필요)

21명의 공개 v0.4 합성 환자를 대상으로 MEVA의 결정론적 검증기를 살펴볼 수 있는 네 가지 방법 — 어느 것도 AI 모델이 필요하지 않습니다:

공개 호스팅 샌드박스 (설치 불필요): 라이브 샌드박스 열기

로컬 브라우저 샌드박스:

pip install -e ".[playground]"
streamlit run streamlit_app.py

로컬 CLI 플레이그라운드:

python3 examples/playground.py demo
python3 examples/playground.py list-patients
python3 examples/playground.py verify --patient-id <id> --category allergy --assertion present --value "Peanut"

전체 로컬 AI 모드 (선택 사항, Ollama 필요 — 아래 AI 없이 실행되는 기능 참조).

네 가지 모두 동일한 서비스 계층(meva.playground)을 공유하며 MEVA의 실제 수정되지 않은 검증기를 호출합니다 — 직접 주장(카테고리/주장/값)을 진술하면 MEVA가 실제 기록된 데이터와 대조하여 전체 출처와 함께 SUPPORTED/CONTRADICTED/UNSUPPORTED/UNVERIFIABLE을 반환합니다. 네 가지 모드가 어떻게 다른지를 포함한 전체 세부 사항: docs/playground.md.

호스팅된 샌드박스의 스크린샷(안내 모드, 검증 결과, 고급 모드)은 이 README 상단의 MEVA 작동 살펴보기를 참조하십시오.

문서

범위 및 안전

MEVA는 오직 합성(Synthea 생성) 환자 데이터만 사용합니다 — 실제 환자 데이터는 포함되어 있지 않으며 기여되어서도 안 됩니다. 진단이나 치료 권고를 수행하지 않으며, 임상적으로 검증되지 않았습니다. MEVA의 지표(Evidence Grounding Score, Verifiable Claim Coverage 등)는 엔지니어링/연구 벤치마크 지표로, 모델의 클레임이 검색된 증거와 일치하는지 측정하는 것이지 의학적 정확성, 진단 정확성 또는 환자 안전을 측정하는 것이 아닙니다. 모든 AI 추론은 Ollama를 통한 로컬 전용이며, MEVA는 유료 또는 클라우드 AI API를 호출하지 않습니다. 전체 내용: docs/safety-and-scope.md.

기여하기

1. 이슈를 선택하세요(또는 제안하세요)

2. 저장소를 포크하세요

3. 브랜치를 만드세요

4. 변경 사항을 적용하세요

5. pytest를 실행하세요

6. 풀 리퀘스트를 여세요

전체 설정, 테스트 세부 사항, FHIR 지원 추가 방법, 벤치마크 케이스(합성 데이터만), 검증기 테스트 또는 모델 어댑터 추가 방법은 CONTRIBUTING.md를 참조하세요. 또한 CODE_OF_CONDUCT.md를 읽어 주세요.

첫 기여를 찾고 계신가요?

공개 GitHub 이슈를 확인하세요: https://github.com/Tanz2024/meva-health-ai/issues

시작하기 좋은 곳은 good first issue 또는 help wanted 라벨이 붙은 이슈입니다.

추가로 제안된 기여 영역은 docs/contributor-issues.md를, 설정 및 제출 지침은 CONTRIBUTING.md를 참조하세요.

라이선스

MEVA의 소스 코드와 로컬에서 생성된 합성 데이터는 Apache License 2.0에 따라 라이선스가 부여됩니다. 타사 종속성 및 모델에는 자체 라이선스가 있습니다 — THIRD_PARTY_NOTICES.md를 참조하세요. 이전 공개 재배포 라이선스 문제(라이선스가 명시되지 않은 저장소에서 복사된 이전 환자 세트)는 해당 데이터를 로컬에서 생성된 Apache-2.0 픽스처로 교체하여 Stage 8A.1에서 해결되었습니다 — 전체 이력은 docs/historical-sample-data-provenance.md를 참조하세요.

인용

MEVA v0.1.0의 인용 메타데이터는 CITATION.cff를 참조하세요.