Zer0Fit

# Zer0Fit — 零镜头预测和表格MCP服务器 <p align="center"> <img src="images/header.png" alt="Zer0Fit — 零镜头预测和表格MCP服务器" width="100%"> </p> Zer0Fit 公开谷歌的 **TimesFM 2.5** （时间序列预测）和 **TabFM v1.0.0** （表格分类/回归）基础模型，通过模型上下文协议（MCP）提供给AI助手。 零镜头意味着无需训练 — 只需将MCP连接到聊天客户端/工具 + 大型语言模型（LLM），附加一个CSV文件，并描述您要预测的内容。无需机器学习专业知识，无需超参数调优，无需特征工程。 <p align="center"> <img src="images/OWUI_example.png" alt="Zer0Fit 工具在 Open WebUI — zer0fit_inspect, zer0fit_forecast, 和 zer0fit_tabular 被发现为MCP工具" width="90%"> <br> <em>（来自 Open WebUI 的示例输出，连接到 Zer0Fit MCP 处理 iris.csv 数据集和用户提示）</em> </p> > ⚠️ **免责声明 — 自担风险使用** > > Zer0Fit 以 **“现状”** 提供，不提供任何类型的保证，仅用于 **研究和教育目的**。开发者不负责底层模型生成的预测、分类或预报的准确性，也不负责解释它们的LLM的准确性。该软件不得用于金融、医疗、法律、安全关键或就业决策的依据。 **TabFM 模型权重为非商业用途** — 请参阅完整的 [免责声明](DISCLAIMER.md)。 [](LICENSE) --- ## 功能 | 功能 | 详情 | |---|---| | **时间序列预测** | 谷歌 TimesFM 2.5（200M 参数）— 从历史数据预测未来值 | | **表格分类** | 谷歌 TabFM v1.0.0 — 从表格数据预测类别/标签 | | **表格回归** | 谷歌 TabFM v1.0.0 — 从表格数据预测连续数值 | | **聊天附件文件支持** | 直接使用 Open WebUI 文件 ID — 在聊天中附加文件，`zer0fit_inspect` 自动解析 | | **文件上传工具** | `zer0fit_upload_csv` 用于未在聊天中附加的文件 — 支持 CSV、XLSX、XLS、JSON、JSONL | | **自动文件检查** | `zer0fit_inspect` 发现列名、数据类型和行数，以便 LLM 选择正确目标 | | **预计算指标** | 分类：准确率、每类精度/召回率/F1、混淆矩阵。回归：R²、MAE、RMSE、MAPE | | **自动文件清理** | 上传的文件在 6 小时后自动删除（可配置） | | **隐私和安全** | 基于 UUID 的文件名防止跨用户文件发现；不会将数据发送给第三方 | | **VRAM 管理** | 基于 TTL 的自动卸载，互斥（一次加载一个模型） | | **多架构** | ARM64（DGX Spark / Blackwell）和 x86_64（RTX 3090 / H100） | | **一键安装** | `./install.sh` 检测架构，配置，构建并启动 | | **MCP 流式HTTP + SSE** | 与 Open WebUI 0.5+ 和 0.10+ 传输模式兼容 | --- ## 先决条件 在运行 `install.sh` 之前，您需要一个具有 NVIDIA GPU 和 Docker 设置的 Linux 服务器。安装程序将检查这些，如果缺少任何一个，安装程序将退出并显示错误。 ### 硬件 | 需求 | 最低 | 备注 | |---|---|---| | **NVIDIA GPU** | 16GB VRAM | 在 RTX 3090（24GB）、H100（80GB）、DGX Spark GB10（128GB）上测试 | | **RAM** | 32GB | 用于将 CSV 加载到主机内存中，然后进行 GPU 分块 | | **磁盘** | 20GB 空闲 | Docker 镜像 + 模型权重（每个约 1.5GB） | ### 软件 | 需求 | 版本 | 安装指南 | |---|---|---| | **操作系统** | Ubuntu 24.04（x86_64 或 ARM64） | — | | **NVIDIA 驱动** | 545+（x86_64）/ 570+（ARM64） | [NVIDIA 驱动下载](https://www.nvidia.com/Download/index.aspx) | | **Docker 引擎** | 24.0+ | [在 Ubuntu 上安装 Docker 引擎](https://docs.docker.com/engine/install/ubuntu/) | | **Docker Compose** | v2+ | 随 Docker 引擎 24+ 包含（`docker compose`） | | **NVIDIA 容器工具包** | 最新 | [安装 NVIDIA 容器工具包](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) | ### 验证您的设置 在开始安装之前运行这些命令。如果任何命令失败，请使用上面的链接安装缺少的先决条件。 ```bash # 1. 验证 NVIDIA 驱动已安装且 GPU 可见 nvidia-smi # 应显示您的 GPU 名称、驱动版本和 CUDA 版本 # 2. 验证 Docker 已安装 docker --version # 应显示 Docker 版本 24.0 或更高 # 3. 验证 Docker Compose v2 可用 docker compose version # 应显示 Docker Compose 版本 v2.x # 4. 验证 NVIDIA 容器工具包 docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu24.04 nvidia-smi # 应在容器内显示您的 GPU — 如果失败，则 NVIDIA 容器工具包未正确配置 ``` > **注意：** Zer0Fit 完全在 Docker 内运行。您 **不需要** 在主机上安装 CUDA、PyTorch 或 Python — 仅需 NVIDIA 驱动、Docker 和 NVIDIA 容器工具包。Docker 镜像包含其他所有内容。 --- ## 快速入门 ### 1. 在 GPU 服务器上部署 ```bash git clone https://github.com/porespellar/Zer0Fit.git cd Zer0Fit ./install.sh ``` 安装程序检测您的架构（ARM64 或 x86_64），选择正确的 CUDA 基础镜像和 PyTorch 轮子，构建 Docker 容器并启动服务器。 ### 2. 连接到 Open WebUI **管理员设置 → 集成 → 管理工具服务器 → 添加连接** - **类型**：MCP / 流式 HTTP - **网址**：`http://YOUR-SERVER-IP:8002/mcp`（流式 HTTP，优先用于 OWUI 0.10+） - **网址**：`http://YOUR-SERVER-IP:8002/sse`（SSE 备用） 您将看到四个已注册的工具： - `zer0fit_inspect` — 发现列名和数据类型从文件中 - `zer0fit_upload_csv` — 上传数据文件从聊天（备用） - `zer0fit_forecast` — 时间序列预测 - `zer0fit_tabular` — 分类和回归 ### 3. 安装技能（推荐） **工作区 → 技能 → 导入技能** → 上传 `openwebui/skill_content.md` 这教导 LLM 哪个工具使用以及如何解释指标。 --- ## 工具选择的工作原理 **LLM 根据您的提示词选择工具 — 而不是通过分析数据。** 相同的 CSV 可以用于预测或分类；LLM 根据您的请求决定。 ### 典型工作流（聊天附件文件） 1. **在 Open WebUI 聊天中附加 CSV 文件** 2. LLM 从 `<file>` 标签中提取 **文件 ID** 3. LLM 调用 `zer0fit_inspect` 以及文件 ID → 发现列名、类型、行数 4. LLM 调用合适的工具根据您的请求： - **预测**: `zer0fit_forecast(file_id, target_column, horizon)` - **分类**: `zer0fit_tabular(file_id, target_column, task_type="classification")` - **回归**: `zer0fit_tabular(file_id, target_column, task_type="regression")` 5. 工具返回预测 **和预计算指标** — LLM 呈现两者 ### 提示 → 工具映射 | 如果您的提示说… | 调用工具 | 模型 | task_type | |---|---|---|---| | "预测", "未来", "预测下一个 N 个月", "外推" | `zer0fit_forecast` | TimesFM 2.5 | `forecast` | | "分类", "分类", "什么物种", "标签" | `zer0fit_tabular` | TabFM v1.0.0 | `classification` | | "预测价格", "估计", "回归", "连续值" | `zer0fit_tabular` | TabFM v1.0.0 | `regression` | | *(文件附加到聊天)* | `zer0fit_inspect` → 然后合适的工具 | *(自动)* | *(自动)* | --- ## 建议尝试的提示 ### 预测（TimesFM） > 附加时间序列 CSV 并输入： *"预测接下来的 12 个月。*" > > 或： *"预测 `乘客` 列的未来值，范围为 12。"* ### 分类（TabFM） > 附加 `iris.csv` 并输入： *"分类物种。*" > > 或： *"预测每个行属于哪个类别。目标列是 `物种`。"* ### 回归（TabFM） > 附加 `california_housing_small.csv` 并输入： *"对该数据进行回归预测 `MedHouseVal`。"* > > 或： *"预测目标列。使用回归。"* --- ## 性能（在 DGX Spark GB10 上测试） | 数据集 | 类型 | 准确率 / R² | 时间 | |---|---|---|---| | Iris（150 行） | 分类 | 94.67% | ~76s | | Boston Housing（506 行） | 回归 | R² = 0.91, MAE = 1.84 | ~90s | | Airline Passengers（144 个点） | 预测 | 捕获季节性模式 | ~11s | --- ## MCP 工具参考 ### `zer0fit_inspect` 发现列名、数据类型和数据文件中的行数。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `file_path` | 字符串 | ✅ | 文件 ID（来自聊天附件）、上传路径或 /app/data 文件名 | **返回：** 列元数据（名称、dtype、非空计数、唯一计数、样本值）。 ### `zer0fit_upload_csv` 上传数据文件到服务器（用于未在聊天中附加的文件）。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `filename` | 字符串 | ✅ | 文件名（必须以 .csv、.xls、.xlsx、.json 或 .jsonl 结尾） | | `content_base64` | 字符串 | ✅ | Base64 编码的文件内容 | **返回：** 服务器端文件路径。文件在 6 小时后自动删除。 ### `zer0fit_forecast` 通过谷歌 TimesFM 2.5 进行零镜头时间序列预测。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `file_path` | 字符串 | ✅ | 文件 ID、上传路径或 /app/data 文件名 | | `target_column` | 字符串 | ✅ | 要预测的数值列 | | `horizon` | int | ✅ | 预测的未来步骤数（**1–256**） | | `datetime_column` | 字符串 | — | 用于时间间隔的可选 datetime 列 | **返回：** 点预测、量化预测（置信区间）和序列长度。 ### `zer0fit_tabular` 通过谷歌 TabFM v1.0.0 进行零镜头表格分类/回归。 | 参数 | 类型 | 必需 | 描述 | |---|---|---|---| | `file_path` | 字符串 | ✅ | 文件 ID、上传路径或 /app/data 文件名 | | `target_column` | 字符串 | ✅ | 要预测的列 | | `task_type` | 枚举 | ✅ | `classification` 或 `regression` | | `max_chunks` | int | — | 最大 1,000 行块数（默认 1，**最大 10**，0 = 最大） | **返回：** 预测、真实值，加上一个 `metrics` 块： **分类指标：** - `accuracy` — 总体正确百分比（例如 0.9467 = 94.67%） - `per_class` — 每类精度、召回率、F1、支持 - `confusion` — 误分类计数（例如 `"versicolor→virginica": 4`） **回归指标：** - `r_squared` — 确定系数 - `mae` — 平均绝对误差（目标单位） - `rmse` — 均方根误差 - `mape_pct` — 平均绝对百分比误差 - `prediction_range` / `ground_truth_range` — 最小/最大值 --- ## 客户端和集成 Zer0Fit 使用 SSE 和 Streamable HTTP 上的标准 MCP。已测试并验证了以下客户端： ### Open WebUI（主要） **管理员设置 → 集成 → 管理工具服务器 → 添加连接** - **类型**：MCP / 流式 HTTP - **网址**：`http://YOUR-SERVER-IP:8002/mcp` - **备用**：`http://YOUR-SERVER-IP:8002/sse` 所有四个工具（`zer0fit_inspect`、`zer0fit_upload_csv`、`zer0fit_forecast`、`zer0fit_tabular`）会自动发现。为了获得最佳结果，还可以安装 [Zer0Fit 技能](openwebui/skill_content.md)。 ### Claude Code 通过 CLI 配置（ `--transport sse` ）: ```bash claude mcp add --transport sse zer0fit http://YOUR-SERVER-IP:8002/sse ``` 或添加到您的 `~/.claude/settings.json`: ```json { "mcpServers": { "zerofit": { "transport": "sse", "url": "http://YOUR-SERVER-IP:8002/sse" } } } ``` 所有工具都会自动发现。像 *"检查 iris 数据集并分类物种。"* 这样，使用自然语言调用它们。 **项目上下文：** 仓库包括一个 [`CLAUDE.md`](CLAUDE.md) 文件（由 Claude Code 自动加载），其中包含架构、约定和常用命令。 [`claude/skills/zerofit-workflow.md`](.claude/skills/zerofit-workflow.md) 技能教你如何正确使用四个 MCP 工具。 ### Codex CLI 通过 CLI 配置（ `--url` 用于 Streamable HTTP ）: ```bash codex mcp add zer0fit --url http://YOUR-SERVER-IP:8002/mcp` ``` 然后使用 `codex exec`： ```bash codex exec "Use zer0fit to inspect data and classify the species." ``` **项目上下文：** 仓库包括一个 [`AGENTS.md`](AGENTS.md) 文件（由 Codex CLI 自动加载），其中包含架构、约定、常用命令和 Zer0Fit MCP 工具使用说明。 ### 不原生支持 | 客户端 | 原因 | |---|---| | **OpenCode** | MCP 支持仅限于stdio 传输，不原生支持 SSE/HTTP 连接 | | 变量 | 默认值 | 描述 | |---|---|---| | `ZER0FIT_VRAM_TTL` | `300` | 空闲秒数后自动卸载模型从 GPU VRAM | | `ZER0FIT_PORT` | `8002` | MCP 服务器暴露的端口 | | `ZER0FIT_UPLOAD_TTL_HOURS` | ``6` | 文件自动删除小时数 | | `ZER0FIT_LOG_LEVEL` | `INFO` | Python 日志级别 | | `ZER0FIT_UPLOAD_DIR` | `/app/data/uploads` | 上传文件目录 | | `ZER0FIT_WEBUI_DIR` | `/app/webui_data/uploads` | Open WebUI 文件 ID 解析的上传目录 | | `ZER0FIT_MAX_UPLOAD_MB` | `50` | 最大上传文件大小（MB） | | `ZER0FIT_DEBUG` | `false` | 启用 Starlette 调试模式（会泄露回溯信息 — 仅用于开发） | --- ## 限制和可配置性 Zer0Fit 强制实施几项限制，以保护 GPU 服务器免受 OOM 崩溃、预测失控和 JSON 响应过大。这些是硬编码的常量，位于 `server.py` 中，您可以根据硬件调整它们。 | 限制 | 默认值 | 位置 | 原因 | 如何更改 | |---|---|---|---|---| | **预测范围** | 1–256 | `server.py` `zer0fit_forecast` 处理程序 | TimesFM 编译为 `max_horizon=256`；更大的值会导致推理错误 | 编辑验证检查，还要更新 `max_horizon` 在 `model_manager.py:_load_timesfm_locked()` | | **表格最大块数** | 10 | `server.py` `MAX_CHUNKS_LIMIT` | 每个块 = 1,000 行。无限块会导致 GPU 内存不足和巨大的 JSON 响应，可能会崩溃 MCP 连接 | 更改 `MAX_CHUNKS_LIMIT` 常量在 `server.py` | | **块大小** | 1,000 行 | `pipelines.py` `TABFM_CHUNK_SIZE` | 控制多少行适合单个 GPU 前向传递 | 编辑常量；更大 = 更多上下文但更多 VRAM | | **上下文大小** | 512 行 | `pipelines.py` `TABFM_IN_CONTEXT_SIZE` | 每块的行数用作零镜头学习的“示例” | 编辑常量；更大 = 更准确但更多 VRAM | | **上下文窗口** | 1,024 个令牌 | `model_manager.py` `max_context` 在 `ForecastConfig` 中 | TimesFM 输入上限（编译模型） | 编辑 `max_context` 在 `_load_timesfm_locked()` | | **上传 TTL** | 6 小时 | `ZER0FIT_UPLOAD_TTL_HOURS` 环境变量 | 自动清理上传的文件以防止磁盘填满 | 在 `docker-compose.yml` 中设置环境变量 | | **VRAM TTL** | 300 秒 | `ZER0FIT_VRAM_TTL` 环境变量 | 自动卸载空闲模型以释放 GPU 内存 | 在 `docker-compose.yml` 中设置环境变量 | | **允许的数据路径** | `/app/data/`、`/app/webui_data/` | `server.py` `ALLOWED_ABS_DIRS` | 安全 — 限制服务器可以读取的文件目录 | 编辑 `_resolve_path()` 中的元组 | | **上传文件名熵** | 128 位 UUID | `server.py` `uuid.uuid4().hex` | 防止可预测的文件名和跨用户文件发现 | 不建议更改 | ### 增加表格块限制 如果您有大 GPU（例如 80GB H100）并且需要处理超过 10,000 行/请求： ```python # 在 server.py 中更改： MAX_CHUNKS_LIMIT = 10 # → 20, 50 等 ``` ### 增加预测范围 如果您需要超过 256 步的预测，同时需要更新验证和模型配置： ```python # 1. 在 server.py 中更新验证： if horizon <= 0 or horizon > 512: # was 256 # 2. 在 model_manager.py 中更新 ForecastConfig： tfm.compile( timesfm.ForecastConfig( max_horizon=512, # was 256 ... ) ) ``` --- ## 项目结构 ``` Zer0Fit/ ├── install.sh # 架构感知的单命令安装程序 ├── .env.example # 配置参考 ├── Dockerfile # 多架构（ARM64 + x86_64） ├── docker-compose.yml # GPU 配置文件，读取 .env ├── requirements.txt # 固定的 Python 依赖项 ├── model_manager.py # VRAM 管理器（TTL，互斥） ├── pipelines.py # 多格式读取器，分块，降采样 ├── server.py # MCP 服务器（端口 8002，流式 HTTP + SSE） ├── README.md # 此文件 ├── ARCHITECTURE.md # 技术设计文档 ├── DISCLAIMER.md # 无保证，使用风险自担声明 ├── CLAUDE.md # Claude Code 项目上下文（自动加载） ├── AGENTS.md # Codex CLI 项目说明（自动加载） ├── LICENSE # Apache 2.0 ├── ATTRIBUTION.md # 第三方模型归属 ├── .claude/ │ └── skills/ │ └── zerofit-workflow.md # Claude Code Zer0Fit MCP 工具技能 ├── docs/ │ └── DEPLOYMENT_GUIDE.md # 完整指南，非 ML 专家 ├── openwebui/ │ └── skill_content.md # Open WebUI 技能（markdown） └── data/ ├── iris.csv # 示例：分类（150 行） ├── california_housing_small.csv # 示例：回归（2,500 行） └── airline_passengers.csv # 示例：预测（144 个点） ``` --- ## 文档说明 | 文档 | 受众 | 内容 | |---|---|---| | **[免责声明](DISCLAIMER.md)** | 所有用户 | 无保证，仅供研究使用，责任限制 | | **[部署和使用指南](docs/DEPLOYMENT_GUIDE.md)** | 任何人 | 完整部署 + Open WebUI 设置 + 示例 + 故障排除 | | **[架构](ARCHITECTURE.md)** | 开发者 | VRAM 状态机，管道拓扑，硬件矩阵 | | **[Open WebUI 技能](openwebui/)** | Open WebUI 管理员 | 用于指导 LLM 工具选择的技能 | | **[Claude 说明](CLAUDE.md)** | Claude Code 用户 | 项目上下文 — 架构，约定，命令（自动加载） | | **[Claude Code 技能](.claude/skills/zerofit-workflow.md)** | Claude Code 用户 | 使用 Zer0Fit 的 MCP 工具的技能 — 工作流程，限制，解释 | | **[代理](AGENTS.md)** | Codex CLI 用户 | 项目说明 — 架构，命令，MCP 工具使用（自动加载） | --- ## 致谢与许可证 本项目在 **Apache License, Version 2.0** 下许可。详见 [LICENSE](LICENSE) 获取详细信息。 ### Google TimesFM 2.5 - **来源**: [google-research/timesfm](https://github.com/google-research/timesfm) - **许可证**: Apache License, Version 2.0 - **版权**: 2024–2026 Google LLC - **引用**: *Das, A., et al. "A decoder-only foundation model for time-series forecasting." ICML 2024.* — [论文](https://openreview.net/forum?id=jn2iTJas6h) ### Google TabFM v1.0.0 - **来源**: [google-research/tabfm](https://github.com/google-research/tabfm) - **许可证**: TabFM 非商业许可证 v1.0（权重）；Apache 2.0（源代码） - **版权**: 2026 Google LLC - **引用**: *TabFM: A Zero-Shot Foundation Model for Tabular Data* — [Google 研究博客](https://research.google/blog/introducing-tabfm-a-zero-shot-foundation-model-for-tabular-data/) ### 示例数据集 - **鸢尾花** — R.A. Fisher, 1936. 公共领域基准数据集。 - **航空公司乘客** — Box & Jenkins, 1976. 公共领域时间序列数据集。 - **加利福尼亚住房** — Pace & Barry, 1997. 公共领域回归数据集。 TimesFM 在 Apache License 2.0 的条款下使用。TabFM 源代码为 Apache 2.0，但 **TabFM 模型权重受 TabFM 非商业许可证 v1.0 约束** — 禁止商业使用权重。原始模型权重未做任何修改。本项目为这些模型提供服务器/传输层 — 模型本身是单独的作品，具有其自己的许可证。详见 [DISCLAIMER.md](DISCLAIMER.md) 和 [ATTRIBUTION.md](ATTRIBUTION.md) 获取详细信息。