yzhao062/pyod

A Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. 60+ detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.

PyOD – Python 이상치 탐지 (v3)

개요 – 다양한 데이터 유형(표 형식, 시계열, 그래프, 텍스트, 이미지, 오디오)을 위한 60개 이상의 이상 탐지 알고리즘을 번들로 제공하는 성숙한 오픈 소스 Python 라이브러리입니다. 버전 3에는 에이전트 준비 오케스트레이션 계층인 ADEngine과 자연어 스킬(od-expert)이 추가되어 대규모 언어 모델 에이전트(Claude Code, Codex 또는 MCP 호환 LLM)가 코드를 작성하지 않고도 탐지 워크플로를 구동할 수 있습니다.

주요 기둥

기둥	의미
다중 모달	6가지 데이터 유형에 걸친 61개 탐지기를 다루는 통합 API.
전체 수명 주기	원시 데이터부터 점수화된 이상, 설명, 다음 단계 안내까지 한 번의 호출로.
에이전트 기반	LLM은 `od-expert` 스킬 또는 MCP 도구(예: `list_detectors`, `run_detection`)를 통해 PyOD를 호출할 수 있습니다.
가장 많이 사용됨	>46M 다운로드, 벤치마크 기반 모델 라우팅, 많은 기업 채택자.

빠른 설치

pip install pyod                     # 핵심 라이브러리
# 에이전트용 선택적 확장
pip install pyod[mcp]                # MCP 호환 LLM
pyod install skill                    # Claude Code / Codex 스킬 설치

언제든지 pyod info를 실행하여 버전, 탐지기 수, 환경에 맞는 활성화 경로를 확인하세요.

최소 예제(클래식 API)

from pyod.models.iforest import IForest
clf = IForest()
clf.fit(X_train)                     # 정상 패턴 학습
train_scores = clf.decision_scores_  # 훈련 데이터의 이상 점수
test_scores  = clf.decision_function(X_test)  # 새 데이터의 점수

동일한 fit/predict 인터페이스는 61개 탐지기 모두에서 작동합니다.

세 가지 사용 계층

계층	사용 시기	진입점
1 – 클래식 API	사용할 탐지기를 알고 있는 경우.	`from pyod.models.<mod> import <Detector>`
2 – ADEngine	PyOD가 탐지기를 자동으로 선택, 비교, 평가하도록 하는 경우.	`from pyod.utils.ad_engine import ADEngine`
3 – 에이전트 기반	LLM과의 자연어 대화를 통해 탐지를 구동하는 경우.	`od-expert` 스킬(Claude Code / Codex) 또는 MCP 서버(`python -m pyod.mcp_server`).

계층 2와 3은 ADEngine에 의해 지원되며, 데이터 프로파일링, 모델 라우팅, 훈련(SUOD 병렬 처리), 점수화, 결과 설명을 오케스트레이션합니다.

에이전트 상호 작용(예시)

Claude Code 또는 Codex 사용자는 "태아 심박수 데이터 세트에서 비정상적인 심박 패턴을 찾아주세요." 와 같은 요청을 입력할 수 있습니다. od-expert 스킬은 요청을 ADEngine 워크플로로 변환하고, 선택된 탐지기를 실행하며, 간결한 설명과 다음 단계 제안을 반환합니다. MCP 서버는 MCP 호환 LLM이 호출할 수 있는 10개의 무상태 도구(예: list_detectors, plan_detection, run_detection)를 노출합니다.

생태계 및 벤치마크

벤치마크: ADBench(표 형식), NLP-ADBench(텍스트), TSB-AD(시계열), BOND(그래프) – 모두 문서에서 링크됩니다.
관련 프로젝트: PyGOD(그래프 AD), TODS(시계열), AD-LLM(LLM 기반 AD) 등.
성능: SUOD 기반의 빠른 병렬 훈련과 Numba JIT를 사용한 모델별 속도 향상.

문서 및 리소스

전체 API 참조: https://pyod.readthedocs.io/en/latest/ (표 형식, 시계열, 그래프, 임베딩, ADEngine, 유틸리티).
설치 가이드, 튜토리얼, 예제 갤러리는 문서 사이트에서 호스팅됩니다.
영향 페이지에는 학술 인용, 기업 배포(Walmart, Databricks, Ericsson 등), 서적, 강좌, 팟캐스트가 나열됩니다.

PyOD를 선택해야 하는 경우

많은 이상 탐지 알고리즘과 데이터 유형을 다루는 단일 라이브러리가 필요한 경우.
대규모 벤치마크에 기반한 자동 모델 선택을 원하는 경우.
탐지를 LLM 기반 워크플로(Claude, Codex 또는 MCP 호환 모델)에 통합할 계획인 경우.
최신 오케스트레이션 기능을 제공하면서 안정적이고 하위 호환되는 API(fit/predict)를 중시하는 경우.

라이선스

BSD-3-Clause 라이선스 하에 오픈 소스.