Day 34：部署与上线
学习目标
今天我们进入整个AI项目开发周期的关键里程碑——部署与上线。在前面几周的学习中，你已经掌握了AI Agent的核心架构设计、Prompt工程、RAG系统搭建、评估体系、成本优化和安全权限设计。但所有这些工作成果目前还只存在于你的开发环境中。要把它们变成一个真正可用的线上服务，你需要解决一系列工程化的问题：如何容器化你的应用？如何部署后端服务、数据库和向量数据库？如何管理环境变量和配置？如何确保服务的健康状态可监控？以及如何为团队提供上线文档和演示环境。今天的内容将带你走完从开发到上线的最后一公里。
一、Docker容器化——让应用在任何环境中一致运行
Docker是现代应用部署的基础设施。它的核心价值在于解决”在我机器上能跑”这个古老的问题。通过容器化，你的应用和它所有的依赖项被打包成一个标准化的单元，在任何安装了Docker的环境中都能以完全相同的方式运行。对于AI应用来说，这一点尤其重要，因为AI应用的依赖链条比传统Web应用更复杂——Python运行环境、各种机器学习库、模型文件、系统级依赖（如CUDA驱动）等等。
在开始写Dockerfile之前，你需要先理清你的应用到底由哪些组件构成。一个典型的AI Agent系统通常包含：FastAPI后端服务、向量数据库服务（如Milvus或Chroma）、关系型数据库（如PostgreSQL，用于存储用户数据、会话记录等）、可能的Redis缓存服务、以及可选的Nginx反向代理。这些组件之间的关系需要通过Docker Compose来编排。
Dockerfile的编写有几个关键原则需要遵循。第一是使用合适的基础镜像。对于Python应用，不要使用完整的Ubuntu镜像，而应该使用slim版本或者Alpine版本来减小镜像体积。AI应用通常需要一些系统级依赖（如编译工具链），slim镜像比Alpine镜像在兼容性上更好，因为Alpine使用的musl libc与很多Python包的预编译二进制不兼容。第二是多阶段构建。在构建阶段安装编译工具和依赖，在运行阶段只拷贝必要的产物，这样最终的镜像不包含编译工具，体积更小也更安全。第三是合理利用Docker的缓存机制。把不常变化的层（如系统依赖安装）放在前面，把经常变化的层（如应用代码拷贝）放在后面，这样在代码更新时只需要重建后面的层，构建速度更快。
在半导体制造的AI项目部署中，你可能还需要考虑一些特殊的因素。比如，某些客户环境可能要求离线部署——由于安全政策，生产网络不允许访问外部互联网。这意味着你的Docker镜像需要在有网络的环境中预先构建好，然后通过离线方式传输到生产环境中。所有的Python依赖包、模型文件、甚至基础镜像都需要提前准备离线版本。
Docker Compose文件的设计需要定义所有服务的配置和它们之间的依赖关系。你的docker-compose文件应该包含后端服务的定义（端口映射、环境变量、卷挂载）、数据库服务的定义（持久化存储、初始配置）、向量数据库服务的定义（内存和磁盘配置）、以及网络配置（服务间的通信）。使用Docker Compose的好处是，团队中的任何人只需要一条命令就能在本地启动完整的系统环境，大大降低了环境配置的门槛。
在容器化的过程中，你还需要注意一些常见的陷阱。比如时区设置——Docker容器默认使用UTC时区，如果你的业务逻辑涉及时区相关的时间处理（如按日期查询报告、计算工时等），需要显式设置容器的时区。再比如文件编码——容器的默认语言环境可能不支持中文，需要安装中文语言包并设置正确的编码。这些细节看似微不足道，但在实际运行中可能引发难以排查的问题。
二、FastAPI部署——让后端服务稳定运行
FastAPI是一个高性能的Python Web框架，非常适合作为AI Agent系统的后端服务。它的异步支持使得处理并发请求非常高效，自动生成的API文档降低了前后端协作的成本。但从开发环境到生产部署，FastAPI还需要一些额外的配置才能稳定运行。
在生产环境中，你不应该直接使用FastAPI的开发服务器（uvicorn的开发模式）。你需要使用Gunicorn作为进程管理器，配合Uvicorn的工作器来运行FastAPI应用。Gunicorn负责管理多个工作进程，当一个工作进程崩溃时自动重启，保证服务的可用性。Uvicorn工作器负责处理ASGI协议，把请求传递给FastAPI应用。
工作进程的数量需要根据服务器的CPU核心数和应用的特性来配置。对于CPU密集型的AI应用（比如在本地运行模型推理），通常设置为CPU核心数加一。对于IO密集型的应用（主要是调用外部API，如OpenAI的服务），可以设置更多的进程，因为大部分时间进程都在等待网络响应。你可以通过压力测试来确定最优的进程数配置。
FastAPI部署还需要配置几个关键中间件。CORS中间件用于处理跨域请求——如果你的前端和后端部署在不同的域名下，必须配置CORS才能正常通信。在生产环境中，CORS配置应该只允许已知的前端域名，而不是使用通配符。超时中间件用于设置请求的最大处理时间——AI系统处理某些复杂查询可能需要较长时间，但也不能无限等待，需要设置合理的超时阈值。请求日志中间件用于记录所有请求的基本信息——请求路径、响应状态码、处理时间等，这些信息对监控和排查问题非常重要。
在半导体制造的AI系统部署中，你可能还需要考虑与现有企业系统的集成。比如通过API与MES（制造执行系统）对接获取实时生产数据，与ERP系统对接获取物料信息，与LDAP或Active Directory对接实现统一身份认证。这些集成需要在部署时配置相应的连接参数和安全证书，确保通信的安全性和可靠性。
FastAPI应用的启动和关闭流程也需要仔细设计。在启动时，应用需要初始化数据库连接池、加载模型和配置、预热缓存。在关闭时，应用需要优雅地处理正在进行中的请求、关闭数据库连接、释放资源。FastAPI提供了startup和shutdown事件钩子来实现这些逻辑。
三、数据库部署——持久化存储的基石
数据库是AI系统的”记忆”，它存储着用户数据、会话历史、文档元数据、评估结果、审计日志等关键信息。在部署数据库时，你需要考虑数据持久化、备份策略、性能优化和安全性等多个方面。
关系型数据库（通常是PostgreSQL）负责存储结构化数据。在Docker部署中，数据库的数据目录必须挂载到宿主机的持久化卷上，否则容器重建后数据会丢失。这个看似基础的配置点在实际部署中经常被忽视，特别是在初次部署时，很多人会忘记配置数据卷，直到某次容器重建导致数据丢失才意识到问题。
PostgreSQL的性能调优在AI系统中尤为重要，因为AI系统可能产生大量的读写操作。每个用户查询都会产生会话记录，每次工具调用都会产生审计日志，每条评估结果都需要存储。主要的调优参数包括：共享缓冲区大小（通常设置为服务器内存的四分之一）、工作内存（影响排序和哈希操作的性能）、以及连接池大小（控制最大并发数据库连接数）。
数据库备份策略是数据安全的重要保障。你需要设计定期自动备份的机制——每天全量备份，每小时增量备份，备份文件存储在与数据库服务器分离的存储系统上。同时需要定期测试备份的恢复流程，确保在数据丢失场景下能够快速恢复。很多团队花了大量精力设计备份策略，但从未测试过恢复流程，等到真正需要恢复时才发现备份数据有损坏或恢复步骤有问题。
数据库的安全性配置包括：使用强密码并定期轮换、限制远程访问的IP范围、启用SSL加密连接、定期更新数据库版本以修复安全漏洞。在多租户场景中，还需要配置行级安全策略（Row Level Security），确保不同租户的数据在数据库层面就是隔离的。
在半导体制造的AI系统中，数据库还需要考虑合规性要求。某些行业标准要求数据保留特定期限、数据删除需要有完整的审计记录、涉及个人信息的数据需要符合隐私保护法规。这些要求在数据库设计阶段就需要纳入考量，而不是在部署后才追加。
四、向量数据库部署——AI系统的记忆引擎
向量数据库是RAG系统的核心组件，它存储着文档的向量表示并支持高效的相似度搜索。向量数据库的部署比关系型数据库有一些特殊的考量。
首先是向量数据库的选型。常见的开源向量数据库包括Milvus、Chroma、Qdrant、Weaviate等。选型时需要考虑几个因素：数据规模（你的文档库有多少条记录，每条记录的向量维度是多少）、查询性能要求（每秒需要支持多少次查询，延迟要求是多少）、部署复杂度（是否支持Docker部署，运维难度如何）、以及与你的技术栈的兼容性。
Milvus是一个功能强大但部署相对复杂的选择，适合大规模生产环境。它支持分布式部署、多种索引类型、以及丰富的查询过滤功能。Chroma则更加轻量，适合中小规模的应用，部署简单但功能相对有限。对于大多数起步阶段的AI项目，建议从轻量级的方案开始，随着数据规模和性能需求的增长再迁移到更强大的方案。
向量数据库的内存管理是一个需要特别关注的配置项。向量索引通常需要加载到内存中才能提供高效的查询性能，所以向量数据库的内存使用量与数据量成正比。你需要根据文档库的大小来配置足够的内存，并预留一定的增长空间。如果内存不足，向量数据库可能退化为磁盘查询，性能会急剧下降。
向量数据库的数据持久化同样重要。与关系型数据库类似，向量数据库的数据需要持久化到宿主机的存储卷上。但向量数据库的特殊之处在于，除了原始向量数据，索引文件的持久化也很关键。如果索引文件丢失，重新构建索引可能需要很长时间——对于数百万条记录的向量库，索引构建可能需要数小时。
向量数据库的版本升级和索引重建也需要预先规划。当你更换Embedding模型（比如从一个512维的模型升级到768维的模型）时，所有文档的向量都需要重新计算，索引也需要完全重建。这是一项耗时且需要停机的操作，需要提前制定详细的执行计划和回滚方案。
在半导体制造的知识库中，文档更新频率是一个重要的部署考量。工艺规范可能每周更新，设备手册可能每季度更新。每次文档更新都需要同步更新向量数据库中的对应记录。你需要设计一个自动化的文档同步流程：文档变更触发事件、更新向量计算、替换向量数据库中的旧记录、更新相关的索引和缓存。
五、环境变量与配置管理——不同环境的差异化配置
任何非平凡的应用都需要在不同环境中使用不同的配置——开发环境用本地数据库和调试模式，测试环境用测试数据集和详细日志，生产环境用正式数据库和精简日志。环境变量是管理这种环境差异的标准方式。
在你的AI系统中，需要通过环境变量管理的配置包括：数据库连接字符串（不同环境连接不同的数据库实例）、API密钥（模型服务的密钥，生产环境使用正式密钥，开发环境使用测试密钥或免费额度）、模型配置（不同环境可能使用不同级别的模型）、日志级别（开发环境用DEBUG级别输出详细日志，生产环境用INFO或WARNING级别减少日志量）、安全配置（CORS允许的域名、会话过期时间等）、以及文件存储路径（不同环境的文件存储位置可能不同）。
环境变量的管理有一个关键原则：永远不要把密钥和敏感信息硬编码在代码中，也不要把它们提交到版本控制系统。所有的密钥应该通过环境变量注入，在开发环境中使用.env文件（这个文件要加入.gitignore），在生产环境中通过Docker Compose的环境变量配置或容器编排工具的密钥管理功能来注入。
配置管理的一个常见模式是”配置层叠”。系统有一套默认配置（写在代码或配置文件中），然后环境变量可以覆盖这些默认值。这样在没有设置环境变量的情况下系统也能以合理的默认值运行，而在需要定制的地方通过环境变量覆盖。FastAPI的配置管理可以使用pydantic的Settings类来实现这种层叠机制，它支持从环境变量、.env文件、以及代码默认值中加载配置，并自动进行类型验证。
在团队协作中，配置管理还需要考虑”配置文档化”。你需要维护一份配置说明文档，列出所有可配置的环境变量、每个变量的用途、合法的取值范围、以及在不同环境中的推荐值。当新成员加入团队或部署到新环境时，这份文档可以大大减少配置出错的可能性。
六、健康检查——让系统状态一目了然
健康检查是线上服务可观测性的基础。你需要能够随时了解系统的各个组件是否正常运行，是否能够正常处理请求。健康检查分为几个层级。
最基础的是存活检查——进程是否还在运行。Docker提供了HEALTHCHECK指令，可以配置定期检查容器内服务是否存活。如果检查失败，Docker会自动重启容器。对于FastAPI应用，存活检查通常是一个简单的API端点，返回200状态码就表示服务存活。
更深入的是就绪检查——服务是否准备好接收请求。一个服务进程可能在运行但还没有完成初始化（比如数据库连接还没建立、模型还没加载完成），这时候它虽然”存活”但还没”就绪”。就绪检查需要验证所有关键依赖是否可用——数据库连接是否正常、向量数据库是否可以查询、外部API是否可达。
最全面的是健康状态检查——提供系统各组件的详细状态信息。一个设计良好的健康检查端点应该返回如下信息：后端服务的运行状态和版本号、数据库连接状态和响应时间、向量数据库的状态和文档数量、缓存服务的状态和命中率、外部API的可达性、以及系统资源使用情况（内存、CPU、磁盘）。
在半导体制造的AI系统中，健康检查还需要包括一些业务级别的指标。比如最近一小时的成功查询率、平均响应时间、自动评分的平均分数、以及缓存命中率。这些指标能够从业务角度反映系统的健康状况，而不仅仅是技术层面的可用性。
健康检查的信息应该通过合适的监控工具来展示和告警。你可以使用Prometheus来采集指标数据，Grafana来创建监控面板，配置告警规则——当关键指标超过阈值时自动通知运维人员。对于AI系统，建议设置以下告警规则：服务不可达告警（最高优先级）、响应时间超过阈值告警、错误率超过阈值告警、以及特定业务指标异常告警。
七、日志查看与问题排查——上线后的日常运维
上线后的系统难免会出现各种问题，完善的日志系统是快速定位和解决问题的关键。日志系统的设计需要在详细程度和存储成本之间取得平衡——过于详细的日志会产生海量数据增加存储和检索成本，过于简略的日志又可能在排查问题时缺乏关键信息。
日志应该按照结构化格式记录，包含以下字段：时间戳、日志级别（DEBUG/INFO/WARNING/ERROR）、请求ID（用于追踪一个请求在系统中的完整处理链路）、用户ID（用于定位特定用户遇到的问题）、操作类型（查询/工具调用/系统事件等）、以及详细的消息内容。
对于AI系统，有一些特殊的日志需求。模型调用的日志需要记录使用的模型名称、输入Token数量、输出Token数量、以及响应时间——这些信息对成本分析和性能优化非常重要。检索的日志需要记录查询向量、返回的候选文档数量、相关性分数分布——这些信息对检索质量分析很有帮助。错误的日志需要特别详细，包括完整的错误堆栈、发生错误时的上下文信息、以及系统当时的状态——这些信息是问题排查的关键线索。
日志的存储和检索建议使用ELK（Elasticsearch、Logstash、Kibana）技术栈或者更轻量的Loki加Grafana方案。这些工具提供了强大的日志搜索和分析能力，可以帮助你快速在海量日志中找到相关信息。
在团队协作中，日志的使用还需要建立一些规范。比如定义统一的错误码体系——每个错误码对应一类已知问题，附带排查指南和解决方案。当团队成员遇到某个错误码时，可以直接查阅对应指南快速定位问题。这对于7乘24小时运行的制造环境特别重要——夜班遇到问题的人员可能不是系统的开发者，详细的错误码和排查指南能够帮助他们独立解决大部分常见问题。
八、Demo账号与上线文档——让系统可体验可理解
上线不是终点，而是运营的起点。你需要让团队成员、利益相关者和潜在用户能够快速了解和体验你的系统。这就需要准备好Demo环境和上线文档。
Demo环境的设计目标是让用户能够在不涉及真实数据的情况下体验系统的核心功能。你需要准备几套Demo数据——典型的半导体工艺文档样本、预设的问答示例、以及一些能展示系统能力特点的演示场景。Demo账号应该有受限的权限，只能访问Demo数据，不能访问任何真实的生产数据。
Demo数据的准备需要用心设计。它应该覆盖系统的主要功能场景，但又不能太复杂让用户迷失。理想情况下，你应该准备一个演示脚本——列出一组建议的查询，按顺序执行这些查询能够完整展示系统的各种能力。在半导体制造的演示中，你可以设计这样的流程：先问一个简单的事实查询展示检索能力，再问一个需要跨文档推理的复杂问题展示综合分析能力，然后问一个需要调用工具的查询展示Agent的自主决策能力，最后展示报告生成功能。
上线文档是系统运营的重要基础设施。一份完整的上线文档应该包含以下内容：系统架构概述（各组件的角色和相互关系）、部署指南（从零开始部署的详细步骤）、配置说明（所有可配置参数的说明和建议值）、运维手册（日常运维操作、常见问题排查、备份恢复流程）、API文档（FastAPI自动生成的文档通常就够用了）、以及用户使用指南（面向非技术用户的操作说明）。
上线文档的编写有一个常见的陷阱——开发者在编写文档时自然地使用了很多技术术语和内部概念，但文档的读者可能不具备相同的技术背景。所以在写文档时，要时刻考虑目标读者是谁。面向运维人员的文档可以深入技术细节，面向管理者的文档应该聚焦在系统能力和业务价值上，面向最终用户的文档应该用最平实的语言描述操作步骤。
上线文档还应该包含一个版本更新日志。每次系统更新时，记录变更的内容、变更的原因、以及可能的影响。这个日志不仅帮助团队了解系统的演变历史，在排查问题时也很有帮助——当一个新问题出现时，首先查看最近是否有相关的变更。
上线前还需要做一次全面的安全审查。检查所有的默认密码是否已更改、API密钥是否已轮换、不必要的调试端点是否已关闭、日志中是否包含敏感信息、以及所有的安全配置是否已按照设计文档正确设置。这次审查最好由开发团队之外的独立人员来执行，以避免”灯下黑”——开发者可能对自己代码中的安全问题视而不见。
在实际的上线过程中，建议采用灰度发布的策略。不要一次性把所有用户切换到新的AI系统，而是先选择一小批用户（比如一个产线或一个部门）进行试用，在试用过程中密切监控系统表现和收集用户反馈。如果发现问题可以快速回退，影响范围也是可控的。只有当灰度阶段验证了系统的稳定性和实用性后，才逐步扩大覆盖范围，最终实现全量上线。在半导体制造这种对稳定性要求极高的行业中，灰度发布不仅是一种建议，更是一种必须遵循的上线纪律。
此外，上线后需要建立一个明确的运营支持机制。指定专门的负责人（可以是轮值的）负责日常监控系统状态、处理用户反馈、以及协调紧急问题的修复。在初期阶段，建议每天进行一次系统状态回顾，确认各项指标是否正常，是否有需要紧急处理的问题。随着系统稳定运行，回顾频率可以逐步降低到每周一次。
今日实践任务总结
今天的实践任务是把你的AI系统从开发环境搬到可运行的生产环境。第一项任务是Docker化项目，为每个服务组件编写Dockerfile，然后编写docker-compose文件来编排所有服务。确保在全新的环境中只通过docker-compose up命令就能启动完整系统。
第二项任务是部署后端服务，将FastAPI应用配置为生产模式运行，包括Gunicorn加Uvicorn的进程管理、CORS中间件配置、请求日志中间件、以及优雅关闭的钩子函数。
第三项任务是部署向量数据库，选择合适的向量数据库方案，配置数据持久化和索引管理，设计文档更新时的向量同步流程。
第四项任务是配置环境变量，梳理系统中所有需要通过环境变量管理的配置项，编写.env.example文件作为模板，编写配置说明文档。
第五项任务是生成部署文档，编写一份完整的部署指南，涵盖系统架构说明、部署步骤、配置说明、运维手册、常见问题排查指南。同时准备Demo环境和Demo数据，确保新用户可以快速体验系统的核心功能。