AI 项目结构：先把产品层、编排层和评估资产分开，再谈目录树
AI 项目结构最容易被写成前后端分工和文件夹示例，但真正决定可维护性的，是产品层、模型编排层、工具层、评估数据和提示词资产是否被明确拆开。
01.AI 项目结构最容易误写成“多几个文件夹就行”
很多关于 AI 项目结构的文章，会直接给出类似这样的目录：
- •
components - •
hooks - •
services - •
utils
这类目录本身没错，但它没有回答 AI 项目最关键的问题：
- •提示词和模型配置放哪
- •工作流编排代码和普通业务 API 怎么隔离
- •评估数据集、坏例子和测试资产放哪
- •工具适配层和产品逻辑如何解耦
所以 AI 项目结构更适合被理解成“工程边界设计”，而不是一个好看的目录树。
02.先按变化原因拆，而不是按技术名词拆
一个很实用的原则是：
会因为同一种原因一起变化的代码，尽量放在一起。
对 AI 项目来说，最常见的变化原因通常不是“这是前端还是后端”，而更像：
- •产品交互变了
- •模型编排变了
- •工具或数据源变了
- •评估标准变了
如果目录结构看不出这些变化边界，后面迭代会越来越难。
03.一条更实用的 AI 项目结构，通常由五层组成
1. 产品体验层
这一层主要承接：
- •页面和组件
- •输入输出呈现
- •会话状态
- •上传和反馈交互
它的职责是把能力变成产品，不应该直接承担模型编排细节。
2. 接口与服务层
这一层负责：
- •API 契约
- •鉴权
- •幂等
- •请求分流
- •后台任务入口
它更像产品层和编排层之间的稳定边界。
3. 编排与工作流层
AI 项目真正最容易失控的部分，通常在这里：
- •模型路由
- •工具调用
- •检索
- •状态机
- •长任务执行
如果这部分和普通 REST API、数据库读写混在一起，系统会很快变得难以维护。
4. 工具与数据适配层
这一层负责：
- •外部 API 适配
- •数据源访问
- •文件处理
- •向量库或检索适配
它应该是受限边界，而不是让业务代码到处直接调外部系统。
5. 评估与资产层
这是很多 AI 项目最容易缺失的一层：
- •提示词模板
- •评估样本集
- •历史坏例子
- •配置版本
- •基线结果
没有这层，项目即使能跑，也很难长期演进。
04.项目结构的关键，不是文件夹名，而是让层与层之间关系清楚
更稳的拆法通常是：
产品层只关心什么
- •输入输出体验
- •状态展示
- •操作反馈
编排层只关心什么
- •任务如何被拆分
- •哪些模型、工具和检索被使用
工具层只关心什么
- •外部资源如何被安全访问
评估层只关心什么
- •如何验证当前系统比之前更好
当这几层分清楚后，即使目录名不同，系统也会更稳。
05.先让项目里的“资产类型”显式存在
很多团队的 AI 项目一开始只有代码，但真正长期需要维护的资产通常还有：
- •prompt
- •policy
- •eval dataset
- •bad cases
- •config profiles
更稳的做法，是从项目一开始就给这些资产留位置。
from typing import Literal
from pydantic import BaseModel
class ProjectAsset(BaseModel):
asset_type: Literal["prompt", "config", "eval_case", "workflow", "tool_adapter"]
owner: str
versioned: bool = True这类显式资产意识，比目录树本身更重要。
06.目录结构应该服务于协作，而不是只服务于单人开发
真实 AI 项目里，常见会同时有这些角色：
- •前端或客户端开发
- •后端工程师
- •AI / workflow 工程师
- •产品或运营
- •QA / 评估同学
如果目录结构只能让一个人看懂，协作成本会越来越高。一个更好的结构，应该让大家都知道：
- •改页面去哪
- •改 workflow 去哪
- •看评估集去哪
- •查配置和 prompt 去哪
07.评估不要只看目录是否整洁，还要看改动是否更可控
项目结构是否合理，更应该看这些结果：
- •新功能是否容易找到落点
- •模型与 workflow 变更是否能独立迭代
- •prompt 和评估资产是否能一起版本化
- •回归问题时是否容易定位
- •新成员是否能快速理解边界
这些指标比“目录是不是很像某个模板”更有价值。
08.三个常见误区
1. 把 AI 代码散落到普通业务服务里
短期看起来方便，长期会让编排、评估和调试边界全部模糊。
2. 没有给 prompt 和评估资产留位置
这样模型迭代最终只会变成“改代码 + 靠感觉验收”。
3. 只按技术框架划分，不按变化边界划分
目录树可能看起来标准，但协作和演进会越来越痛。
09.总结
AI 项目结构真正可交付的价值，不是多摆几个文件夹，而是把产品层、接口层、编排层、工具层和评估资产层的边界做清楚：
- •先按变化原因而不是按名词拆结构
- •让 prompt、workflow 和 eval 数据成为一等资产
- •把外部工具和数据源隔离成明确边界
- •用协作和回归效率，而不是模板相似度来评估结构质量
只要这些边界理顺，AI 项目才更有机会在多人协作和持续迭代中保持可维护。