生成式 AI 的项目结构指南（实战可落地）

生成式AI（GenAI）项目结构指南（实战可落地）以下是一套标准化、模块化的GenAI项目模板，涵盖目录设计、核心文件、最佳实践及启动流程，适用于团队协作与长期维护。

关键设计原则

• 配置与代码分离：通过YAML文件管理模型参数、提示词模板，便于环境切换与协作。
• 模块化拆分：按职责划分src/目录，避免“巨石脚本”，例如：

  llm/：统一模型接口，支持A/B测试与故障回退。

  utils/：封装日志、缓存、限流等通用功能。

• 数据分层管理：

  cache/：减少重复API调用，降低延迟与成本。

  prompts/：版本化提示词（如v1/prompt.yaml），支持回滚与对比。

1. requirements.txt

   固定依赖版本，推荐配合uv或poetry管理环境，例如：

   openai>=1.0.0pandas>=2.0.0python-dotenv>=1.0.0

2. README.md

   包含以下内容：

   架构图（推荐使用Mermaid或Draw.io生成）。

   启动步骤（如pip install -r requirements.txt）。

   评测方法（自动化指标+人工问卷）。

   变更记录（Changelog）。

3. Dockerfile

   锁定运行时环境，确保训练/推理可复现，例如：

   FROM python:3.10-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .CMD ["python", "src/examples/basic_completion.py"]

4. setup.py

   将src/打包为内部库，支持多项目复用，例如：

   from setuptools import setup, find_packagessetup(name="genai_utils", packages=find_packages(where="src"))

• 优先级：YAML配置文件 > 环境变量 > 代码默认值。
• 示例：config/model_config.yamldefault_model: "gpt-4o-mini"temperature: 0.3max_tokens: 2048rate_limit: rpm: 60 # 每分钟请求数 burst: 10 # 突发请求阈值

• 统一异常封装：# src/handlers/error_handler.pyclass RetriableError(Exception): """可重试的异常（如API限流）""" passdef with_retry(fn, retries=3, backoff=0.5): """装饰器：自动重试失败请求""" for i in range(retries): try: return fn() except RetriableError as e: time.sleep(backoff * (2 i)) raise e

• 令牌桶算法：防止配额被打爆，例如：# src/utils/rate_limiter.pyclass TokenBucket: def __init__(self, rpm, burst): self.capacity = burst self.tokens = burst self.last_time = time.time() self.rate = rpm / 60 # 每秒补充的令牌数 def consume(self, tokens=1): now = time.time() elapsed = now - self.last_time self.tokens = min(self.capacity, self.tokens + elapsed * self.rate) self.last_time = now if self.tokens >= tokens: self.tokens -= tokens return True return False

• 统一接口：支持多模型切换与A/B测试，例如：# src/llm/openai.pyclass OpenAIClient: def __init__(self, config): self.config = config def complete(self, prompt): response = openai.Completion.create( model=self.config["default_model"], prompt=prompt, temperature=self.config["temperature"] ) return response.choices[0].text

• 分层缓存：

  内存缓存：functools.lru_cache（适用于小规模数据）。

  本地缓存：cache/目录存储JSON/Pickle文件。

  云缓存：Redis（适用于分布式系统）。

• 代码文档：使用docstring与类型注解（Type Hints），例如：def generate_summary(text: str, max_length: int = 200) -> str: """生成文本摘要 Args: text: 输入文本 max_length: 摘要最大长度 Returns: 摘要字符串 """ ...
• Notebook测试：通过notebooks/response_analysis.ipynb分析生成结果质量。

1. 克隆仓库并安装依赖：git clone <repo_url>uv pip install -r requirements.txt # 或 poetry install
2. 运行最小示例：python -m src.examples.basic_completion --config config/model_config.yaml
3. 验证输出：检查outputs/目录是否生成结果文件。

1. 质量监控

   自动化评测：在eval/目录下实现BLEU、Rouge等指标计算。

   人工问卷：通过Gradio或Streamlit搭建对比界面，收集用户反馈。

2. 成本控制

   Token统计：记录每次请求的输入/输出token数。

   缓存命中率：监控cache/目录的使用频率。

   周报看板：使用Pandas或Metabase生成成本与质量趋势图。

1. 提示词版本化

   目录结构：prompts/<task>/<vX>/prompt.yaml，例如：

   prompts/├─ summarization/│ ├─ v1/prompt.yaml│ └─ v2/prompt.yaml└─ qa/ └─ v1/prompt.yaml

2. 链式推理

   将复杂任务拆分为多个步骤，中间态持久化到data/，例如：

   step1_result = step1(input_data)save_to_disk(step1_result, "data/intermediate/step1.json")step2_result = step2(step1_result)

3. 可观测性

   接入OpenTelemetry或自定义埋点，追踪请求链路、成本与错误率。

通过以上结构与实践，团队可快速搭建可维护、可扩展的GenAI项目，同时平衡质量与成本。