企业官网建设流程全解析

PyCaret 4.0 将项目重新定位为一套开源、可自托管的表格数据机器学习平台，以pip install pycaret即可获得的无状态引擎与一个完整的**Web 控制平面（Control Plane）**为双核心，目标是成为团队真正拥有、可自主部署的 DataRobot / H2O.ai 替代方案。本文以仓库中的 VISION.md 为骨架，结合 ARCHITECTURE.md、ROADMAP.md、STATUS.md 以及packages/engine、services/api、infra/下的真实源码，完整梳理它的产品定位、目标用户、产品闭环、刻意取舍、部署模式与三大工程原则，并落到仓库中的代码与配置证据上。

一、愿景总览：两个层次，一个品牌

PyCaret 4.0 的愿景文档开宗明义地给出定义：PyCaret 是一个开源、自托管的表格数据机器学习平台，其定位是团队能够真正拥有的 DataRobot 与 H2O.ai 的可行替代品。整个产品由两个层次组成：

• PyCaret Engine（引擎）——pip install pycaret即可安装的 Python 库。配置驱动（config-driven）、无状态（stateless）、对 Notebook 友好，构建在 scikit-learn 1.7+ 之上，负责 AutoML、预处理管道、模型训练与评估，并产出不可变的管道制品（immutable pipeline artifacts）。
• PyCaret Control Plane（控制平面）——包装引擎的完整 Web 应用，覆盖认证、工作区（workspaces）、项目（projects）、数据集（datasets）、实验（experiments）、运行（runs）、制品注册中心（artifact registry）、部署与在线推理（deployment & serving）、监控（monitoring）、漂移检测（drift detection）、LLM 辅助实验设计。自托管，可以跑在一台笔记本、单个 Docker 主机上，也可以部署到 Kubernetes + Terraform 云环境。

这两层在仓库的 monorepo 结构中有着清晰的一一对应关系（见 ARCHITECTURE.md）：packages/engine是引擎源码目录，发布为 PyPI 上的pycaret包；services/api是 FastAPI 后端（发布为pycaret-server）；apps/web是 React 单页应用；infra/承载 Docker、Helm 与 Terraform 部署资产。目前引擎版本号为4.0.0a8（见 packages/engine/pycaret/init.py），处于向4.0.0正式版过渡的 soak 阶段。

二、为谁而建：四类目标用户

愿景文档明确了产品服务的四类人群，这直接决定了平台的功能优先级：

1. 数据科学家——希望获得 AutoML 能力，但不愿被任何厂商锁定（no lock-in）。
2. ML 工程师——需要能在公司内部署平台，并且自己拥有制品、日志和管道的团队。
3. 小团队（≤20 人）——需要"训练 → 部署 → 监控 → 改进"的完整闭环，但又不想为 Databricks 之类的商业许可买单。
4. 企业用户——需要在同一套从原型起步的代码中获得 SSO、审计日志和多云部署能力。

这种用户分层在 Control Plane 的能力设计上有直接体现：从 STATUS.md 可以看到，V2 阶段已经落地的角色格子（role lattice）从最初的{admin, member}扩展到了 7 种角色（owner / admin / project_admin / ml_engineer / data_scientist / viewer / service_account），对应企业治理需求；审计日志（AuditLog）中间件则记录所有/api/v1/*的变更型请求（见 app.py）。

三、产品闭环：从 CSV 到线上预测端点的完整循环

愿景文档给出了产品要优化的核心闭环：

Create project Upload dataset Create experiment Run AutoML Compare pipelines Save artifact Deploy endpoint Monitor predictions Ask AI what to improve next

每一步都追求"键盘优先、暗色模式、无营销装饰、无神秘操作、单列表单"的交互体验。这个闭环从代码层面可以逐段验证：

• Create project / Upload dataset：后端有projects、data_sources路由，支持 CSV 上传（64 MB 上限、SHA-256 校验、列采样）以及 S3 / Postgres 连接器注册（见 ARCHITECTURE.md §4.1）；apps/web/src下的DataSourcesSection.tsx、SampleDatasetsBrowserModal.tsx等组件提供上传与浏览界面，datasets/目录还内置了大量示例 CSV。
• Create experiment / Run AutoML：POST /api/v1/experiments/{id}/runs提交运行，RunOrchestrator在线程池中执行setup | create | compare等计划（runs/orchestrator.py）。
• Compare pipelines / Save artifact：运行成功后将拟合管道以 cloudpickle 序列化为制品行；AutoML 搜索模式plan="search"会迭代多个预处理变体并聚合 leaderboard。
• Deploy endpoint / Monitor predictions：POST /runs/{id}/promote将管道提升为工作区级 Pipeline，再创建 Deployment（带 slug + auth_mode + 指标计数器），最终通过POST /api/v1/deployments/{slug}/predict提供推理（ARCHITECTURE.md §4.4）。prediction_logs表记录每次请求，漂移监控（drift monitor）周期性计算 PSI / Cramer's V 并可在中度/严重漂移时触发 webhook 告警。
• Ask AI what to improve next：LLM 顾问系统（LLM consultations）提供数据集分析、实验设计、运行解释、失败调试、部署风险评估、漂移分析六类建议，全部经 LLMRouter 统一路由。

四、刻意不做的事：定位的边界

愿景文档用"Not ..."清单划清了产品的边界，这些边界同样能在仓库中得到印证：

• 不是托管的 SaaS——由用户自己运行。平台包采用双 BSL-1.1 许可保留了未来托管运营的可能。
• 不是 Databricks——不管理集群、Notebook 或数据仓库，只负责"我有一份 CSV"到"我有一个在线预测端点"这段路径。
• 不绑定任何单一 LLM 厂商——Claude 与 OpenAI 通过 provider 路由器平级支持，用户自带 API Key。这一点在代码中有直接体现：services/api/pycaret_server/llm/providers/下存在anthropic_provider.py与openai_provider.py，由get_provider()统一构造。
• 不绑定 MLflow / Comet / Weights & Biases——事件流、制品注册中心等所需机制全部自研，第三方追踪器仅作为可选的 V3 适配器。事件流自研的例证是pycaret/logging/events.py中定义的Event不可变数据类与EventKind字符串枚举，支持 JSON 往返序列化。
• 不是特征商店 / 数据平台——与 Snowflake / Postgres / S3 / BigQuery 做集成，而不是重新实现。

五、四种部署模式

愿景文档给出了产品要随附的部署模式矩阵：

仓库中可验证的实际配置包括：

• 一键本地启动：仓库根目录的 compose.yml 即"git clone && docker compose up"入口，启动 api（FastAPI + 进程内 APScheduler）+ web（nginx 托管的 React UI，反代/api与/ws），SQLite 数据库、上传的 CSV 与拟合.pkl制品都持久化在pycaret-data命名卷中；docker compose down保留数据，docker compose down -v清空一切。
• 生产形态 Compose：infra/docker/docker-compose.prod.yml 提供了 postgres（16-alpine）、redis（7-alpine）、minio（S3 兼容对象存储）与独立 worker 容器的生产形态参考栈，UI 暴露在http://localhost:3020。注释明确说明这是"自托管 OSS 安装"的参考形态，正式生产需自行覆盖密钥。
• Kubernetes / Terraform：infra/helm/pycaret/提供 Helm chart（含 api / web / worker Deployment 模板与 ingress），infra/terraform/{aws,gcp,azure}提供多云模块；根据 STATUS.md 的说明，这两部分属于有意延后的基础设施工作（"leave infra for the end"）。

六、三大工程原则：引擎无状态、配置即契约、制品不可变

愿景文档用三条原则定义了 4.0 与 3.x 的分水岭，它们也是理解整个架构的钥匙：

原则 1：引擎是无状态的

一次调用：result = engine.run(config)。没有隐藏的全局变量，没有setup()之后必须紧跟compare_models()的脆弱调用链。

3.x 中基于ContextVar的会话级隐式状态被彻底移除，Experiment实例彼此独立。仓库中的实现证据：

• 五种任务实验类ClassificationExperiment、RegressionExperiment、ClusteringExperiment、AnomalyExperiment、TimeSeriesExperiment都从 pycaret/tasks/init.py 导出，且均实现为 sklearn 可组合的BaseEstimator子类。
• 引擎的类型化内省 API（pycaret.api）是"无副作用"设计的典范：list_models、describe_model、list_metrics、describe_setup_params全部返回可 JSON 序列化的数据类，不训练任何模型（见 api/init.py）。这套 API 直接驱动 React 侧实验向导的动态表单（<DynamicForm>按ParamKind与引擎声明的group渲染）。
• STATUS.md 记录了一个漫长的"神类抽干"（god-class drain）工程：从 session 22 到 session 46，16 个建模动词、数据访问器、内部训练状态、pull/models/get_metrics、add_metric/remove_metric、get_config/set_config、乃至setup()本身全部脱离_legacy，最终删除了约 22K 行旧代码（含pycaret/internal/pycaret_experiment/与五个oop.py薄包装）。

原则 2：配置即契约

一份RunConfigJSON 同时驱动 Notebook 运行、API 运行、UI 向导运行和 LLM 生成的运行。同一套 schema，四个接口。

在 ARCHITECTURE.md §8 中，RunConfig被画成四路汇集的单一契约：数据集 + 任务 + 预处理 + 模型选择 + 评估 + AutoML + 调参 + 可解释性，统一进入引擎执行。目前仓库中以RunSpec（见 runs/orchestrator.py）承载运行所需的全部信息（run_id、task、target、setup_params、plan、模型 ID、数据来源三元组等），API 层接收松散 dict 存入Run.snapshot，正式化为严格 PydanticRunConfig是 MVP 1 退出条件中剩余的一项。

原则 3：制品不可变，部署有版本

你永远不会修改一个已训练的管道，永远不会部署一个移动的目标。每一次生产预测都可以追溯到一条具体的pipeline_artifact记录。

仓库中的对应实现包括：运行成功后将管道写入制品行（ARTIFACT_DIR/runs/<run_id>/pipeline.pkl+Artifact表）；管道以(workspace_id, name)划分版本族（family_id+version），提升（promote）会递增版本号，并提供POST /deployments/{id}/rollback回滚到族内任意早期版本；DeploymentRegistry使用进程内 LRU 缓存管道并维护 p50/p95 滚动窗口指标（见 ARCHITECTURE.md §4.4）。

七、成功的样子：五条验收性标准

愿景文档以五个"可以做到"的场景定义了成功，每条都在仓库中有落点：

1. 数据科学家 5 行训练模型：pip install pycaret，打开 Notebook，5 行代码完成训练——以 3.x 的方式工作，但更快、跑在现代 sklearn 上。仓库顶部的 canonical API 示例（pycaret/init.py）恰好是五步：构建实验 → fit → compare → predict → save。
2. 团队 5 分钟内获得完整 Control Plane：git clone+docker compose up，localhost:3020上跑起完整控制平面（对应 compose.yml）。
3. 企业terraform apply部署到自家 AWS：获得 SSO + 审计日志并满足合规审查（V2 阶段目标，对应 infra/terraform/aws/）。
4. 分析师零 Python 走完闭环：上传 CSV → 点击 AutoML → 拿到 leaderboard → 点击 Deploy → 上线预测端点（对应前端DeployFromPipelineDialog、PredictTester等组件）。
5. LLM Agent 参与实验设计：读取数据集画像 → 提议RunConfig→ 用户批准 → 确定性引擎执行。这里有一个贯穿始终的关键约束：LLM 输出只是建议（advisory），每次咨询返回suggested_config_json+suggested_action+reasoning_summary+risk_flags，最终由确定性引擎执行用户批准的内容——建议与执行之间始终隔着"人审"这道闸。

八、落地现状：愿景在仓库中的完成度

愿景文档末尾指向了两份关键文件：完整规格见 CONTROL_PLANE_SPEC.md，进度与下一步见 ROADMAP.md 和 STATUS.md。截至 2026-05-08（session 54），实际状态是：

• 引擎 MVP-1 完成：6 个在4.0.0a2中还是NotImplementedError桩的旧动词全部恢复可用；核心依赖从 12 个精简到 10 个（移除imbalanced-learn/category-encoders）；Plotly 绘图模块（pycaret/plots/{classification,regression,feature,clustering,anomaly,time_series}）提供 33 个独立绘图函数，plot_model/evaluate_model通过每种任务各自的绘图注册表分发（16 种分类图、12 种回归图、6 种聚类图、4 种异常检测图、8 种时间序列图）。
• Control Plane V2 功能全部落地：加密密钥（Fernet）、预测日志、试验（trials）、模型库、调度任务（漂移监控 + 重训练）、webhook、实验模板、管道版本化 + 回滚、AutoML 管道搜索、扩展角色格子、备份 / 恢复；数据库表从 session 9 基线的 14 张增长到 26 张；新增pycaret-clientSDK 包。
• 测试规模：引擎 330、后端 115、UI 59，合计 504 项测试；PyPI 引擎版本推进到4.0.0a8。
• 有意延后的事项：生产 Compose（Postgres + MinIO + Redis + Caddy + TLS）、K8s Helm chart 与多云 Terraform、独立services/worker容器（进程内 APScheduler 对 V1 足够）；SSO / Electron 桌面版 / K8s 原生执行属于 V2/V3 长期项。

愿景文档的收尾是一句克制而完整的话："That's the whole product."——整个产品就是：一个无状态、配置驱动、Notebook 友好的 sklearn 原生引擎，加上一个可自托管、覆盖从 CSV 到预测端点全闭环、带 LLM 辅助的控制平面。如果你想深入实现细节，可以按这条阅读路径继续：先读 VISION.md 建立产品心智，再读 ARCHITECTURE.md 理解模块划分与调用链，用 CONTROL_PLANE_SPEC.md 查规格，用 ROADMAP.md 与 STATUS.md 对照进度，最后钻进packages/engine与services/api的源码验证每一个设计决策。