为部署构建 LangChain 项目结构

推荐的项目布局

尽管理想结构可能因应用复杂程度和团队偏好而异，但对于包含 LangGraph 和 LangServe 等现代工具的生产级 LangChain 应用，一种常见且高效的布局通常如下所示：

这是一个可部署 LangChain 应用的典型目录结构，强调职责分离和现代组件。

我们来审视每个主要目录的用途：

• src/ (或 app/): 这是你应用的核心。它包含定义 LangChain 逻辑的 Python 模块和包。
  • 模块化: 在 src/ 内部，根据功能将代码组织到子目录中。常见文件夹包含 graphs/ (用于 LangGraph 有状态工作流)、chains/ (用于 LCEL 可运行组件)、tools/、prompts/ 和 utils/。这种结构有助于隔离逻辑，便于重用和测试。
  • API 入口: 对于生产部署，你通常需要一个 API 服务器。像 server.py 这样的文件通常放置在此处，用于定义 FastAPI 应用和 LangServe 路由。
  • 在 src/ 及其子目录中使用 __init__.py 文件，将它们标记为 Python 包。
• config/: 在这里存放配置文件，按环境分离（例如，default.yaml, production.yaml）。这对于模型参数或提示模板等复杂的非敏感设置很有用。然而，现代应用越来越倾向于依赖代码中定义的 Pydantic Settings 类，这些类直接从环境变量读取，从而减少了对外部 YAML 文件的依赖。
• tests/: 包含所有自动化测试。
  • unit/: 针对独立函数、工具或图节点的测试。
  • integration/: 验证组件之间交互的测试，例如完整的链式执行或代理循环。
• scripts/: 存放用于非主应用流程任务的实用脚本，例如数据摄取、向量存储索引或评估运行。
• notebooks/: 用于试验和原型设计的 Jupyter Notebook。将它们分开能确保实验性代码不与生产逻辑混淆。
• deploy/ (或 infra/): 包含与部署基础设施相关的文件，例如 Kubernetes 清单 (kubernetes/)、Terraform 配置 (terraform/) 或 Helm 图表。
• Dockerfile: 定义如何为你的应用构建容器镜像。它通常位于根目录中，以便构建上下文可以包含所有项目文件。
• 依赖管理文件:
  • requirements.txt 或 pyproject.toml: 定义运行时依赖项。对于 Poetry 或 PDM 等现代工具，使用 pyproject.toml 是标准做法，允许严格的版本锁定以及更便捷的开发依赖管理。
• 环境变量:
  • .env: 应在 .gitignore 中列出。包含秘密信息（API 密钥）和本地设置。
  • .env.example: 一个模板文件，展示所需变量但没有具体值。
• .gitignore: 指定 Git 应该忽略的文件（例如，.env, __pycache__/, 本地数据）。
• README.md: 提供关于设置、测试和部署流程的基本文档。