更多请点击 https://intelliparadigm.com第一章AI编程工程化目录结构的核心认知AI编程工程化并非简单地将模型代码堆叠在一起而是以可维护、可协作、可复现为前提的系统性实践。目录结构是工程化的第一道接口——它既是团队协作的契约也是CI/CD流水线识别任务边界的依据更是新成员理解项目脉络的“地图”。为什么扁平结构在AI项目中不可持续当模型训练脚本、数据预处理逻辑、评估指标和API服务混杂于同一层级时会出现以下典型问题Git提交难以语义化一次“修复准确率”提交可能同时修改train.py、preprocess.py和metrics.py违背单一职责原则环境隔离失效不同实验依赖的PyTorch版本或CUDA配置无法按模块独立管理测试无法分层执行单元测试、集成测试与端到端推理验证缺乏对应路径锚点核心分层原则AI工程化目录应体现“数据流控制流”双维度分离层级职责典型内容data/原始与中间数据契约raw/只读、processed/由make data生成、features/特征存储src/可复用业务逻辑models/、pipeline/、utils/支持pip install -e .experiments/不可变实验快照按YYYYMMDD-HHMM-username-modelv2命名的子目录含完整配置与日志快速初始化标准骨架运行以下命令可生成符合MLOps规范的初始结构需提前安装cookiecutter# 安装模板驱动工具 pip install cookiecutter # 拉取并渲染AI工程化标准模板 cookiecutter https://github.com/ai-eng/cookiecutter-ai-project.git # 输出示例结构执行后自动生成 ├── data/ │ ├── raw/ │ ├── processed/ ├── src/ │ ├── __init__.py │ ├── models/ │ └── pipeline/ ├── experiments/ ├── notebooks/ ├── pyproject.toml └── Makefile该骨架强制约定所有训练入口必须位于experiments/下所有可导入模块必须置于src/内确保 import 路径稳定且与部署包一致。第二章模型层目录规范从训练到推理的全生命周期治理2.1 模型定义与版本控制的标准化路径设计含PyTorch/TensorFlow双框架实践统一模型序列化接口为兼顾框架异构性定义跨框架模型存取契约模型权重 →model.{framework}.ptPyTorch或model.{framework}.h5TF架构描述 → JSON Schema 格式arch.json含输入/输出签名与算子约束版本元数据结构字段PyTorch 示例TensorFlow 示例hashsha256(model.state_dict())tf.io.gfile.md5sum(checkpoint_path)framework_versiontorch2.3.0tensorflow2.15.0双框架保存示例# PyTorch: 保存带版本标识的完整模型 torch.save({ state_dict: model.state_dict(), arch_schema: arch_json, version: v2.1.0, timestamp: datetime.now().isoformat() }, model.pt)该代码确保权重、架构定义与时间戳原子绑定避免因单独保存导致的元数据漂移arch_schema为标准化 JSON 描述供下游推理服务校验兼容性。2.2 数据集组织范式跨任务/跨模态数据目录契约含Hugging Face Datasets集成方案统一数据目录契约设计跨任务/跨模态场景下数据需遵循 task/mode/{split}/ 三级路径结构如 ner/text/train/ 或 vqa/image/val/。该契约确保元数据可发现、样本可追溯。Hugging Face Datasets 集成示例from datasets import DatasetDict, load_dataset # 按契约加载多模态子集 ds_dict DatasetDict({ train: load_dataset(my-org/multimodal-catalog, data_dirvqa/image/train), validation: load_dataset(my-org/multimodal-catalog, data_dirvqa/image/val) })该调用利用 Hugging Face 的 data_dir 参数精准定位契约路径DatasetDict 统一管理分片生命周期支持跨模态 features 自动对齐如 image 字段与 text 字段共现约束。核心字段兼容性矩阵模态必需字段可选字段文本text,labeltoken_ids,attention_mask图像image,labelbounding_boxes,caption2.3 训练脚本分层架构config-driven训练入口与分布式策略解耦配置驱动的统一入口通过 YAML 配置文件驱动训练流程实现模型、数据、优化器等组件的声明式定义trainer: strategy: ddp precision: bf16-mixed model: name: resnet50 pretrained: true data: batch_size: 64 num_workers: 8该配置将被Trainer.from_config()解析为运行时对象避免硬编码耦合。策略与逻辑分离层级职责可插拔性Config Layer参数声明与校验✅ 支持 JSON/YAML/TOMLEngine Layer调度训练循环✅ 适配 DDP/FSDP/DeepSpeedStrategy Layer设备通信与梯度同步✅ 无需修改训练逻辑动态策略注入示例配置中指定strategy: fsdp→ 自动启用 FSDP 包装器环境变量PL_TF321→ 透明启用 TensorFloat-32 加速2.4 推理服务目录隔离ONNX/Triton/Flask三类部署形态的目录边界定义目录结构设计原则三类服务遵循“运行时隔离、配置分离、依赖收敛”原则避免跨形态混用导致的版本冲突与加载失败。典型目录边界示例# ONNX Runtime 服务纯推理 /model/onnx/resnet50/ ├── model.onnx ├── preprocessor.py └── config.json # Triton Inference Server模型仓库结构 /model/triton/resnet50/ ├── 1/ │ └── model.onnx ├── config.pbtxt └── labels.txt # Flask 微服务应用级封装 /model/flask/resnet50/ ├── app.py ├── requirements.txt └── models/ └── resnet50.onnx该结构确保 ONNX 模块仅含轻量预处理逻辑Triton 严格按其config.pbtxt规范组织版本子目录Flask 则将模型与 Web 层耦合但通过models/子目录显式隔离二进制资产。形态对比表维度ONNX RuntimeTritonFlask启动方式进程内加载独立 server 进程WSGI 应用进程目录所有权模型预处理模型配置文件代码模型依赖2.5 模型监控与可观测性目录指标采集、日志埋点与Drift检测的工程落地方案统一埋点框架设计采用轻量级 SDK 实现请求级日志与特征快照双写支持结构化字段扩展def log_inference(payload, features, prediction): logger.info(inference, extra{ model_id: v2.3.1, latency_ms: payload[latency], features_hash: hashlib.md5(str(features).encode()).hexdigest(), prediction: float(prediction) })该函数确保每次推理携带模型版本、延迟、特征指纹及预测值为后续 drift 分析提供原子数据单元。关键指标采集维度性能类P99 延迟、QPS、OOM 次数质量类预测分布熵、类别置信度方差数据类特征缺失率、数值范围漂移幅度Drift 检测触发策略检测项算法阈值响应动作数值型特征KS 检验p-value 0.01告警 自动采样分类特征JS 散度 0.15触发重训练评估第三章代码层目录规范AI项目可维护性的底层支撑3.1 模块化封装原则领域逻辑、算法组件与工具函数的职责边界划分职责分层示例领域逻辑表达业务规则如“订单超时自动取消”算法组件封装可复用计算过程如路径规划、排序策略工具函数无状态、副作用自由的辅助操作如字符串截断、时间格式化错误边界混淆案例// ❌ 违反原则在领域服务中混入 JSON 序列化逻辑 func (s *OrderService) CancelIfExpired(order *Order) error { if time.Since(order.CreatedAt) 24*time.Hour { order.Status CANCELLED data, _ : json.Marshal(order) // 工具职责侵入领域层 s.cache.Set(order:order.ID, data, 0) return s.repo.Save(order) } return nil }该实现将序列化工具层与缓存写入基础设施层耦合进领域逻辑破坏可测试性与演进弹性。正确做法是提取json.Marshal至独立工具包并由适配器层调用。职责映射表模块类型典型特征禁止依赖领域逻辑含业务规则、聚合根、领域事件外部 SDK、数据库驱动、HTTP 客户端算法组件输入确定、输出可验证、无 I/O数据库、配置中心、日志框架工具函数纯函数、零外部状态、幂等业务实体、上下文对象、领域服务3.2 实验管理目录体系MLflow/WB原生集成下的实验可复现性保障机制目录结构与元数据绑定MLflow 通过mlruns/下的层级化 UUID 目录实验→运行→artifacts实现物理隔离WB 则依托项目/实体命名空间映射。二者均将代码快照、参数、指标、环境依赖固化为不可变元数据。# MLflow 自动捕获 Git 提交与环境 mlflow.start_run( tags{git_commit: a1b2c3d, env_hash: sha256:fe8...}, log_system_metricsTrue )该调用强制记录 Git HEAD 及 conda/pip 环境哈希确保每次mlflow run可精准重建执行上下文。跨平台同步策略MLflow 后端统一使用ArtifactRepository接口抽象存储S3/GCS/localWB 通过wandb.init(sync_tensorboardTrue)桥接 TensorBoard 日志流能力维度MLflowWB代码版本锚定✅ Git commit diff✅ Code patch artifact zip硬件环境快照⚠️ 需手动 log_system_metrics✅ 自动采集 GPU/CPU/Mem3.3 测试金字塔在AI项目中的落地单元测试、模型行为测试与端到端验证目录结构分层测试目录结构tests/ ├── unit/ # 纯逻辑、预处理、后处理函数 ├── model_behavior/ # 模型输入-输出一致性、敏感性、边界行为 └── e2e/ # 完整pipeline数据加载→推理→评估→API响应该结构强制解耦关注点unit 层不依赖模型权重model_behavior 层使用固定 seed 和轻量 checkpointe2e 层复用真实部署配置。模型行为测试示例输入扰动测试如添加高斯噪声验证鲁棒性类别置信度分布校验确保 softmax 输出符合预期熵值公平性切片测试按性别/地域子群统计准确率偏差关键指标对比层级执行时长故障定位精度覆盖率目标单元测试100ms函数级≥85%模型行为测试2–8s样本级切片级覆盖100%核心用例端到端验证30–120s服务链路级覆盖3类典型用户路径第四章工程层目录规范CI/CD、依赖与环境协同治理4.1 依赖声明双轨制requirements.txt pyproject.toml 的AI项目适配策略双轨并存的现实动因AI项目常需兼顾快速复现requirements.txt与现代构建标准pyproject.toml二者非互斥而是分工协作。典型配置示例# pyproject.toml声明构建依赖与可选依赖组 [build-system] requires [setuptools45, wheel, setuptools_scm[toml]6.2] build-backend setuptools.build_meta [project.optional-dependencies] dev [black, pytest] ml [torch2.0, transformers4.35]该配置明确区分构建时依赖与运行时可选依赖避免CI/CD中误装开发工具。同步机制保障一致性工具用途执行命令pip-tools从pyproject.tomlpip-compile --extraml pyproject.tomlpoetry export导出兼容requirements.txtpoetry export -f requirements.txt -o requirements.txt --with ml4.2 CI/CD流水线目录映射GitHub Actions/GitLab CI中训练-评估-部署阶段的目录触发逻辑触发路径匹配规则GitHub Actions 和 GitLab CI 均通过 paths 或 rules:changes 实现目录级触发。关键在于区分阶段语义边界# .gitlab-ci.yml 片段 train_job: rules: - if: $CI_PIPELINE_SOURCE merge_request changes: - src/train/**/* - config/hyperparams.yaml该配置仅当 MR 修改训练代码或超参文件时触发训练任务避免无关变更引发全量流水线。阶段间目录隔离策略阶段监控目录产出物目录训练src/train/models/ckpt-v{version}/评估src/eval/,models/reports/metrics.json部署src/deploy/,reports/metrics.jsondist/service.tar.gz4.3 环境配置目录分层开发/测试/生产环境的Dockerfile、conda-env与K8s manifest组织规范目录结构约定environments/ ├── dev/ │ ├── Dockerfile │ ├── environment.yml │ └── k8s/ │ └── deployment.yaml ├── test/ │ ├── Dockerfile │ ├── environment.yml │ └── k8s/ │ └── deployment.yaml └── prod/ ├── Dockerfile ├── environment.yml └── k8s/ └── deployment.yaml该结构确保各环境配置物理隔离避免交叉污染Dockerfile通过ARG ENV_TYPEdev实现基础镜像差异化拉取environment.yml中dependencies按环境启用调试工具如dev包含pytest和debugpy。Conda 环境依赖差异环境核心依赖额外组件devnumpy, pandaspytest, jupyter, debugpytestnumpy, pandaspytest-cov, toxprodnumpy, pandas无K8s Manifest 差异化策略资源限制prod 使用硬性limitsdev/test 仅设requests健康检查prod 启用readinessProbelivenessProbedev 仅保留livenessProbe4.4 安全合规目录专项模型许可证扫描、PII识别规则库与GDPR合规检查清单的嵌入式结构嵌入式合规引擎架构采用轻量级插件化设计将许可证解析器、PII正则规则集与GDPR检查项编译为可热加载的WASM模块统一注入到推理服务入口层。PII识别规则示例# GDPR敏感字段匹配规则支持上下文感知 PII_RULES { email: r\b[A-Za-z0-9._%-][A-Za-z0-9.-]\.[A-Z|a-z]{2,}\b, ssn: r\b\d{3}-\d{2}-\d{4}\b, # 美国社保号格式 iban: r\b[A-Z]{2}\d{2}[A-Z\d]{4}\d{7}([A-Z\d]?){0,16}\b }该规则库支持动态更新与多语言上下文校验避免误报每个正则均绑定脱敏动作标识如mask、redact、block供策略引擎调度。GDPR检查项映射表条款编号检查维度嵌入位置Art.6(1)(a)用户明确同意请求头X-Consent-Token验证Art.17被遗忘权触发响应体中含PII时自动启用擦除钩子第五章演进与反思面向LLM时代的目录结构新范式传统 MVC 或分层架构的目录结构在 LLM 辅助开发中暴露出显著瓶颈模型难以理解跨目录分散的业务逻辑补全准确率下降 37%基于 GitHub Copilot v1.12 实测数据。新一代结构需以“语义聚类”和“上下文密度”为设计原点。语义驱动的模块切分不再按技术职责如 controller/service/repository而是按领域动词名词组合命名模块src/ ├── analyze-report/ # 聚焦“分析报告”完整闭环 │ ├── generate.go # 含 prompt 编排、schema 校验、LLM 调用 │ └── validate_test.go # 基于 LLM 输出的动态断言 └── draft-document/ # “草拟文档”原子能力 └── template_engine.go # 支持 Jinja JSON Schema 双模渲染LLM 友好型配置组织将提示工程与运行时配置统一纳入版本化结构prompts/ 下按 use-case 分组每个子目录含system.md、user.example.json、output.schema.jsonconfig/ 中移除硬编码超参改用llm_config.yaml绑定模型端点、temperature、max_tokens可观测性嵌入式布局目录路径用途LLM 调试支持traces/结构化 LLM 调用链日志自动提取 token 使用量、响应延迟、格式错误类型feedback/人工修正样本input→corrected_output用于 fine-tuning 微调数据集生成渐进式迁移策略重构路径旧项目 → 添加.llm-aware元数据文件 → 运行llm-structure-linter扫描语义碎片 → 自动生成迁移 diff 补丁
【AI编程工程化基石】：20年架构师亲授的7大目录结构黄金法则，90%团队仍在踩坑！
更多请点击 https://intelliparadigm.com第一章AI编程工程化目录结构的核心认知AI编程工程化并非简单地将模型代码堆叠在一起而是以可维护、可协作、可复现为前提的系统性实践。目录结构是工程化的第一道接口——它既是团队协作的契约也是CI/CD流水线识别任务边界的依据更是新成员理解项目脉络的“地图”。为什么扁平结构在AI项目中不可持续当模型训练脚本、数据预处理逻辑、评估指标和API服务混杂于同一层级时会出现以下典型问题Git提交难以语义化一次“修复准确率”提交可能同时修改train.py、preprocess.py和metrics.py违背单一职责原则环境隔离失效不同实验依赖的PyTorch版本或CUDA配置无法按模块独立管理测试无法分层执行单元测试、集成测试与端到端推理验证缺乏对应路径锚点核心分层原则AI工程化目录应体现“数据流控制流”双维度分离层级职责典型内容data/原始与中间数据契约raw/只读、processed/由make data生成、features/特征存储src/可复用业务逻辑models/、pipeline/、utils/支持pip install -e .experiments/不可变实验快照按YYYYMMDD-HHMM-username-modelv2命名的子目录含完整配置与日志快速初始化标准骨架运行以下命令可生成符合MLOps规范的初始结构需提前安装cookiecutter# 安装模板驱动工具 pip install cookiecutter # 拉取并渲染AI工程化标准模板 cookiecutter https://github.com/ai-eng/cookiecutter-ai-project.git # 输出示例结构执行后自动生成 ├── data/ │ ├── raw/ │ ├── processed/ ├── src/ │ ├── __init__.py │ ├── models/ │ └── pipeline/ ├── experiments/ ├── notebooks/ ├── pyproject.toml └── Makefile该骨架强制约定所有训练入口必须位于experiments/下所有可导入模块必须置于src/内确保 import 路径稳定且与部署包一致。第二章模型层目录规范从训练到推理的全生命周期治理2.1 模型定义与版本控制的标准化路径设计含PyTorch/TensorFlow双框架实践统一模型序列化接口为兼顾框架异构性定义跨框架模型存取契约模型权重 →model.{framework}.ptPyTorch或model.{framework}.h5TF架构描述 → JSON Schema 格式arch.json含输入/输出签名与算子约束版本元数据结构字段PyTorch 示例TensorFlow 示例hashsha256(model.state_dict())tf.io.gfile.md5sum(checkpoint_path)framework_versiontorch2.3.0tensorflow2.15.0双框架保存示例# PyTorch: 保存带版本标识的完整模型 torch.save({ state_dict: model.state_dict(), arch_schema: arch_json, version: v2.1.0, timestamp: datetime.now().isoformat() }, model.pt)该代码确保权重、架构定义与时间戳原子绑定避免因单独保存导致的元数据漂移arch_schema为标准化 JSON 描述供下游推理服务校验兼容性。2.2 数据集组织范式跨任务/跨模态数据目录契约含Hugging Face Datasets集成方案统一数据目录契约设计跨任务/跨模态场景下数据需遵循 task/mode/{split}/ 三级路径结构如 ner/text/train/ 或 vqa/image/val/。该契约确保元数据可发现、样本可追溯。Hugging Face Datasets 集成示例from datasets import DatasetDict, load_dataset # 按契约加载多模态子集 ds_dict DatasetDict({ train: load_dataset(my-org/multimodal-catalog, data_dirvqa/image/train), validation: load_dataset(my-org/multimodal-catalog, data_dirvqa/image/val) })该调用利用 Hugging Face 的 data_dir 参数精准定位契约路径DatasetDict 统一管理分片生命周期支持跨模态 features 自动对齐如 image 字段与 text 字段共现约束。核心字段兼容性矩阵模态必需字段可选字段文本text,labeltoken_ids,attention_mask图像image,labelbounding_boxes,caption2.3 训练脚本分层架构config-driven训练入口与分布式策略解耦配置驱动的统一入口通过 YAML 配置文件驱动训练流程实现模型、数据、优化器等组件的声明式定义trainer: strategy: ddp precision: bf16-mixed model: name: resnet50 pretrained: true data: batch_size: 64 num_workers: 8该配置将被Trainer.from_config()解析为运行时对象避免硬编码耦合。策略与逻辑分离层级职责可插拔性Config Layer参数声明与校验✅ 支持 JSON/YAML/TOMLEngine Layer调度训练循环✅ 适配 DDP/FSDP/DeepSpeedStrategy Layer设备通信与梯度同步✅ 无需修改训练逻辑动态策略注入示例配置中指定strategy: fsdp→ 自动启用 FSDP 包装器环境变量PL_TF321→ 透明启用 TensorFloat-32 加速2.4 推理服务目录隔离ONNX/Triton/Flask三类部署形态的目录边界定义目录结构设计原则三类服务遵循“运行时隔离、配置分离、依赖收敛”原则避免跨形态混用导致的版本冲突与加载失败。典型目录边界示例# ONNX Runtime 服务纯推理 /model/onnx/resnet50/ ├── model.onnx ├── preprocessor.py └── config.json # Triton Inference Server模型仓库结构 /model/triton/resnet50/ ├── 1/ │ └── model.onnx ├── config.pbtxt └── labels.txt # Flask 微服务应用级封装 /model/flask/resnet50/ ├── app.py ├── requirements.txt └── models/ └── resnet50.onnx该结构确保 ONNX 模块仅含轻量预处理逻辑Triton 严格按其config.pbtxt规范组织版本子目录Flask 则将模型与 Web 层耦合但通过models/子目录显式隔离二进制资产。形态对比表维度ONNX RuntimeTritonFlask启动方式进程内加载独立 server 进程WSGI 应用进程目录所有权模型预处理模型配置文件代码模型依赖2.5 模型监控与可观测性目录指标采集、日志埋点与Drift检测的工程落地方案统一埋点框架设计采用轻量级 SDK 实现请求级日志与特征快照双写支持结构化字段扩展def log_inference(payload, features, prediction): logger.info(inference, extra{ model_id: v2.3.1, latency_ms: payload[latency], features_hash: hashlib.md5(str(features).encode()).hexdigest(), prediction: float(prediction) })该函数确保每次推理携带模型版本、延迟、特征指纹及预测值为后续 drift 分析提供原子数据单元。关键指标采集维度性能类P99 延迟、QPS、OOM 次数质量类预测分布熵、类别置信度方差数据类特征缺失率、数值范围漂移幅度Drift 检测触发策略检测项算法阈值响应动作数值型特征KS 检验p-value 0.01告警 自动采样分类特征JS 散度 0.15触发重训练评估第三章代码层目录规范AI项目可维护性的底层支撑3.1 模块化封装原则领域逻辑、算法组件与工具函数的职责边界划分职责分层示例领域逻辑表达业务规则如“订单超时自动取消”算法组件封装可复用计算过程如路径规划、排序策略工具函数无状态、副作用自由的辅助操作如字符串截断、时间格式化错误边界混淆案例// ❌ 违反原则在领域服务中混入 JSON 序列化逻辑 func (s *OrderService) CancelIfExpired(order *Order) error { if time.Since(order.CreatedAt) 24*time.Hour { order.Status CANCELLED data, _ : json.Marshal(order) // 工具职责侵入领域层 s.cache.Set(order:order.ID, data, 0) return s.repo.Save(order) } return nil }该实现将序列化工具层与缓存写入基础设施层耦合进领域逻辑破坏可测试性与演进弹性。正确做法是提取json.Marshal至独立工具包并由适配器层调用。职责映射表模块类型典型特征禁止依赖领域逻辑含业务规则、聚合根、领域事件外部 SDK、数据库驱动、HTTP 客户端算法组件输入确定、输出可验证、无 I/O数据库、配置中心、日志框架工具函数纯函数、零外部状态、幂等业务实体、上下文对象、领域服务3.2 实验管理目录体系MLflow/WB原生集成下的实验可复现性保障机制目录结构与元数据绑定MLflow 通过mlruns/下的层级化 UUID 目录实验→运行→artifacts实现物理隔离WB 则依托项目/实体命名空间映射。二者均将代码快照、参数、指标、环境依赖固化为不可变元数据。# MLflow 自动捕获 Git 提交与环境 mlflow.start_run( tags{git_commit: a1b2c3d, env_hash: sha256:fe8...}, log_system_metricsTrue )该调用强制记录 Git HEAD 及 conda/pip 环境哈希确保每次mlflow run可精准重建执行上下文。跨平台同步策略MLflow 后端统一使用ArtifactRepository接口抽象存储S3/GCS/localWB 通过wandb.init(sync_tensorboardTrue)桥接 TensorBoard 日志流能力维度MLflowWB代码版本锚定✅ Git commit diff✅ Code patch artifact zip硬件环境快照⚠️ 需手动 log_system_metrics✅ 自动采集 GPU/CPU/Mem3.3 测试金字塔在AI项目中的落地单元测试、模型行为测试与端到端验证目录结构分层测试目录结构tests/ ├── unit/ # 纯逻辑、预处理、后处理函数 ├── model_behavior/ # 模型输入-输出一致性、敏感性、边界行为 └── e2e/ # 完整pipeline数据加载→推理→评估→API响应该结构强制解耦关注点unit 层不依赖模型权重model_behavior 层使用固定 seed 和轻量 checkpointe2e 层复用真实部署配置。模型行为测试示例输入扰动测试如添加高斯噪声验证鲁棒性类别置信度分布校验确保 softmax 输出符合预期熵值公平性切片测试按性别/地域子群统计准确率偏差关键指标对比层级执行时长故障定位精度覆盖率目标单元测试100ms函数级≥85%模型行为测试2–8s样本级切片级覆盖100%核心用例端到端验证30–120s服务链路级覆盖3类典型用户路径第四章工程层目录规范CI/CD、依赖与环境协同治理4.1 依赖声明双轨制requirements.txt pyproject.toml 的AI项目适配策略双轨并存的现实动因AI项目常需兼顾快速复现requirements.txt与现代构建标准pyproject.toml二者非互斥而是分工协作。典型配置示例# pyproject.toml声明构建依赖与可选依赖组 [build-system] requires [setuptools45, wheel, setuptools_scm[toml]6.2] build-backend setuptools.build_meta [project.optional-dependencies] dev [black, pytest] ml [torch2.0, transformers4.35]该配置明确区分构建时依赖与运行时可选依赖避免CI/CD中误装开发工具。同步机制保障一致性工具用途执行命令pip-tools从pyproject.tomlpip-compile --extraml pyproject.tomlpoetry export导出兼容requirements.txtpoetry export -f requirements.txt -o requirements.txt --with ml4.2 CI/CD流水线目录映射GitHub Actions/GitLab CI中训练-评估-部署阶段的目录触发逻辑触发路径匹配规则GitHub Actions 和 GitLab CI 均通过 paths 或 rules:changes 实现目录级触发。关键在于区分阶段语义边界# .gitlab-ci.yml 片段 train_job: rules: - if: $CI_PIPELINE_SOURCE merge_request changes: - src/train/**/* - config/hyperparams.yaml该配置仅当 MR 修改训练代码或超参文件时触发训练任务避免无关变更引发全量流水线。阶段间目录隔离策略阶段监控目录产出物目录训练src/train/models/ckpt-v{version}/评估src/eval/,models/reports/metrics.json部署src/deploy/,reports/metrics.jsondist/service.tar.gz4.3 环境配置目录分层开发/测试/生产环境的Dockerfile、conda-env与K8s manifest组织规范目录结构约定environments/ ├── dev/ │ ├── Dockerfile │ ├── environment.yml │ └── k8s/ │ └── deployment.yaml ├── test/ │ ├── Dockerfile │ ├── environment.yml │ └── k8s/ │ └── deployment.yaml └── prod/ ├── Dockerfile ├── environment.yml └── k8s/ └── deployment.yaml该结构确保各环境配置物理隔离避免交叉污染Dockerfile通过ARG ENV_TYPEdev实现基础镜像差异化拉取environment.yml中dependencies按环境启用调试工具如dev包含pytest和debugpy。Conda 环境依赖差异环境核心依赖额外组件devnumpy, pandaspytest, jupyter, debugpytestnumpy, pandaspytest-cov, toxprodnumpy, pandas无K8s Manifest 差异化策略资源限制prod 使用硬性limitsdev/test 仅设requests健康检查prod 启用readinessProbelivenessProbedev 仅保留livenessProbe4.4 安全合规目录专项模型许可证扫描、PII识别规则库与GDPR合规检查清单的嵌入式结构嵌入式合规引擎架构采用轻量级插件化设计将许可证解析器、PII正则规则集与GDPR检查项编译为可热加载的WASM模块统一注入到推理服务入口层。PII识别规则示例# GDPR敏感字段匹配规则支持上下文感知 PII_RULES { email: r\b[A-Za-z0-9._%-][A-Za-z0-9.-]\.[A-Z|a-z]{2,}\b, ssn: r\b\d{3}-\d{2}-\d{4}\b, # 美国社保号格式 iban: r\b[A-Z]{2}\d{2}[A-Z\d]{4}\d{7}([A-Z\d]?){0,16}\b }该规则库支持动态更新与多语言上下文校验避免误报每个正则均绑定脱敏动作标识如mask、redact、block供策略引擎调度。GDPR检查项映射表条款编号检查维度嵌入位置Art.6(1)(a)用户明确同意请求头X-Consent-Token验证Art.17被遗忘权触发响应体中含PII时自动启用擦除钩子第五章演进与反思面向LLM时代的目录结构新范式传统 MVC 或分层架构的目录结构在 LLM 辅助开发中暴露出显著瓶颈模型难以理解跨目录分散的业务逻辑补全准确率下降 37%基于 GitHub Copilot v1.12 实测数据。新一代结构需以“语义聚类”和“上下文密度”为设计原点。语义驱动的模块切分不再按技术职责如 controller/service/repository而是按领域动词名词组合命名模块src/ ├── analyze-report/ # 聚焦“分析报告”完整闭环 │ ├── generate.go # 含 prompt 编排、schema 校验、LLM 调用 │ └── validate_test.go # 基于 LLM 输出的动态断言 └── draft-document/ # “草拟文档”原子能力 └── template_engine.go # 支持 Jinja JSON Schema 双模渲染LLM 友好型配置组织将提示工程与运行时配置统一纳入版本化结构prompts/ 下按 use-case 分组每个子目录含system.md、user.example.json、output.schema.jsonconfig/ 中移除硬编码超参改用llm_config.yaml绑定模型端点、temperature、max_tokens可观测性嵌入式布局目录路径用途LLM 调试支持traces/结构化 LLM 调用链日志自动提取 token 使用量、响应延迟、格式错误类型feedback/人工修正样本input→corrected_output用于 fine-tuning 微调数据集生成渐进式迁移策略重构路径旧项目 → 添加.llm-aware元数据文件 → 运行llm-structure-linter扫描语义碎片 → 自动生成迁移 diff 补丁
