Waveguardclient

WaveGuard Python SDK

基于波动物理的异常检测，而非机器学习。
一次 API 调用。完全无状态。适用于任何数据类型。

基准测试 • 快速开始 • 使用场景 • 示例 • MCP / Claude • API 参考

什么是 WaveGuard？

WaveGuard 是一个通用异常检测 API。向它发送任意数据——服务器指标、金融交易、日志文件、传感器读数、时间序列——即可获得异常分数、置信度，以及说明哪些特征触发了警报。

无需训练流水线。无需管理模型。无状态。只需一次 API 调用。

Your data  →  WaveGuard API (GPU)  →  Anomaly scores + explanations

在底层，它使用 GPU 加速的波动物理，而非机器学习。你不需要了解或关心其中的物理原理——所有计算都在服务端完成。

Modal 控制面板与 API 端点

查看 Modal 时，你会看到已部署的函数（例如 fastapi_app、gpu_scan、gpu_fingerprint）。 这些是计算/运行时单元，而非 HTTP 路由列表。

若要查看所有在线 API 端点，请使用：

• OpenAPI 文档：https://gpartin--waveguard-api-fastapi-app.modal.run/docs
• OpenAPI JSON：https://gpartin--waveguard-api-fastapi-app.modal.run/openapi.json

基准测试（v2.2）

在 6 种真实场景中，对比 WaveGuard v2.2 与 scikit-learn（每种场景均使用 10 个训练样本和 10 个测试样本）。

简而言之：WaveGuard v2.2 在 6 种场景中赢下 4 种，平均 F1 分数为 0.76；与 sklearn 方法相比具有竞争力，同时无需任何机器学习专业知识。

F1 分数（精确率与召回率的调和平均数）

v2.2 新增内容

多分辨率评分会跟踪每个特征的局部晶格能量，并计算全局指纹距离。这可以检测细微的单特征异常（例如 10 个 IoT 传感器中有 3 个出现漂移），而 v2.1 的全局平均方法会漏掉这类异常。IoT F1 分数从 0.30 提升至 0.87。

何时选择 WaveGuard 而非 sklearn

pip install WaveGuardClient scikit-learn
python benchmarks/benchmark_vs_sklearn.py

扩展基准测试：WaveGuard 在全部 12 个公开基准数据集上的 F1 分数均排名第 #1。请在 HuggingFace 查看完整对比。

真实场景验证：检测加密货币崩盘

WaveGuard 为加密货币风险扫描器 CryptoGuard 提供支持。基于 7 次历史崩盘进行回测（LUNA、FTX、Celsius、3AC、UST、SOL/FTX、TITAN）：

2022 年 10 月 16 日，WaveGuard 将 FTT（FTX 代币）标记为 CAUTION——比其暴跌 94% 提前了 23 天——而 Z 分数分析未发现任何异常。

在召回率相同的情况下，误报比统计基线减少 5 倍。完整结果： CryptoGuard 回测。

安装

pip install WaveGuardClient

就是这样。唯一的依赖项是 requests。所有物理计算均在服务器端通过 GPU 运行。

在 RapidAPI 上免费获取 API 密钥 →

快速入门

同一个 scan() 调用适用于任何数据类型。以下是三个不同行业的示例——使用同一个 API：

检测服务器是否遭到入侵

from waveguard import WaveGuard

wg = WaveGuard(api_key="YOUR_KEY")

result = wg.scan(
    training=[
        {"cpu": 45, "memory": 62, "disk_io": 120, "errors": 0},
        {"cpu": 48, "memory": 63, "disk_io": 115, "errors": 0},
        {"cpu": 42, "memory": 61, "disk_io": 125, "errors": 1},
    ],
    test=[
        {"cpu": 46, "memory": 62, "disk_io": 119, "errors": 0},    # ✅ normal
        {"cpu": 99, "memory": 95, "disk_io": 800, "errors": 150},   # 🚨 anomaly
    ],
)

for r in result.results:
    print(f"{'🚨' if r.is_anomaly else '✅'}  score={r.score:.1f}  confidence={r.confidence:.0%}")

标记欺诈交易

result = wg.scan(
    training=[
        {"amount": 74.50, "items": 3, "session_sec": 340, "returning": 1},
        {"amount": 52.00, "items": 2, "session_sec": 280, "returning": 1},
        {"amount": 89.99, "items": 4, "session_sec": 410, "returning": 0},
    ],
    test=[
        {"amount": 68.00, "items": 2, "session_sec": 300, "returning": 1},     # ✅ normal
        {"amount": 4200.00, "items": 25, "session_sec": 8, "returning": 0},     # 🚨 fraud
    ],
)

检测日志中的安全事件

result = wg.scan(
    training=[
        "2026-02-24 10:15:03 INFO  Request processed in 45ms [200 OK]",
        "2026-02-24 10:15:04 INFO  Request processed in 52ms [200 OK]",
        "2026-02-24 10:15:05 INFO  Cache hit ratio=0.94 ttl=300s",
    ],
    test=[
        "2026-02-24 10:20:03 INFO  Request processed in 48ms [200 OK]",                  # ✅ normal
        "2026-02-24 10:20:04 CRIT  xmrig consuming 98% CPU, port 45678 open",             # 🚨 crypto miner
        "2026-02-24 10:20:05 WARN  GET /api/users?id=1;DROP TABLE users-- from 185.x.x",  # 🚨 SQL injection
    ],
    encoder_type="text",
)

同一个客户端。同一个 scan() 调用。适用于任何数据。

使用场景

WaveGuard 适用于任何结构化、数值或文本数据。只要你能描述什么是“正常”，它就能检测偏差。

**API 并不了解你的领域。**它只知道“正常”是什么样子（即你的训练数据），并标记任何偏离的情况。因此它具有通用性——由你提供上下文，由它负责检测。

支持的数据类型

根据数据形状自动检测，无需配置：

示例

每个示例都是可运行的 Python 脚本，会调用在线 API：

pip install WaveGuardClient
python examples/iot_predictive_maintenance.py

MCP 服务（Claude Desktop）

首个可作为 MCP 工具使用的基于物理学的异常检测器。 让任何 AI Agent 都能检测异常——无需任何机器学习知识。

快速设置

{
  "mcpServers": {
    "waveguard": {
      "command": "uvx",
      "args": ["--from", "WaveGuardClient", "waveguard-mcp"]
    }
  }
}

然后询问 Claude：“这些传感器读数中有异常吗？”——它会自动调用 waveguard_scan。

可用的 MCP 工具

请参阅 MCP Agent Demo 查看可运行示例，或参阅 MCP Integration Guide 了解完整设置流程。

Azure 迁移

Azure Anomaly Detector 将于 2026 年 10 月停用。 WaveGuard 可直接替代：

# Before (Azure) — 3+ API calls, stateful, time-series only
client = AnomalyDetectorClient(endpoint, credential)
model = client.train_multivariate_model(request)   # minutes
result = client.detect_multivariate_batch_anomaly(model_id, data)
client.delete_multivariate_model(model_id)

# After (WaveGuard) — 1 API call, stateless, any data type
wg = WaveGuard(api_key="YOUR_KEY")
result = wg.scan(training=normal_data, test=new_data)  # seconds

详情请参阅 Azure Migration Guide。

API 参考

wg.scan(training, test, encoder_type=None, sensitivity=None)

返回 ScanResult，包含 .results（逐样本结果）和 .summary（汇总结果）。

wg.health() / wg.tier()

健康检查（无需身份验证）和订阅套餐信息。

高级智能方法（v3.3.0）

• wg.counterfactual(...)
• wg.trajectory_scan(...)
• wg.instability(...)
• wg.phase_coherence(...)
• wg.interaction_matrix(...)
• wg.cascade_risk(...)
• wg.mechanism_probe(...)
• wg.action_surface(...)
• wg.multi_horizon_outlook(...)

这些方法直接对应 /v1/* 智能端点，并返回原始 JSON 负载，以便最大限度地兼容快速演进的服务端响应架构。

错误处理

from waveguard import WaveGuard, AuthenticationError, RateLimitError

try:
    result = wg.scan(training=data, test=new_data)
except AuthenticationError:
    print("Bad API key")
except RateLimitError:
    print("Too many requests — back off and retry")

完整 API 参考：docs/api-reference.md

项目结构

WaveGuardClient/
├── waveguard/              # Python SDK package
│   ├── __init__.py         # Public API exports
│   ├── client.py           # WaveGuard client class
│   └── exceptions.py       # Exception hierarchy
├── mcp_server/             # MCP server for Claude Desktop
│   └── server.py           # stdio + HTTP transport
├── benchmarks/             # Reproducible benchmarks vs sklearn
│   ├── benchmark_vs_sklearn.py
│   └── benchmark_results.json
├── examples/               # 9 runnable examples
├── docs/                   # Documentation
│   ├── getting-started.md
│   ├── api-reference.md
│   ├── mcp-integration.md
│   └── azure-migration.md
├── tests/                  # Test suite
├── pyproject.toml          # Package config (pip install -e .)
└── CHANGELOG.md

开发

git clone https://github.com/gpartin/WaveGuardClient.git
cd WaveGuardClient
pip install -e ".[dev]"
pytest

链接

• RapidAPI（获取 API 密钥）：https://rapidapi.com/gpartin/api/waveguard
• 在线 API：https://gpartin--waveguard-api-fastapi-app.modal.run
• 交互式文档（Swagger）：https://gpartin--waveguard-api-fastapi-app.modal.run/docs
• PyPI：https://pypi.org/project/WaveGuardClient/
• Smithery：https://smithery.ai/servers/emergentphysicslab/waveguard
• Glama：https://glama.ai/mcp/connectors/com.emergentphysicslab/waveguard

许可证

MIT——请参阅 LICENSE。