很多事情不真正跑到生产环境你是不知道水有多深的。上个月我带团队做AI商品推荐智能体从接到需求到部署上线整个周期比原计划缩短了接近10倍。以前这套流程少说两三周需求反复对齐、技术方案评审、接口联调、部署配置、监控告警每一步都能卡住人。现在从需求规格说明书开始到用AI生成前后端代码再到本地部署大模型、用Docker Compose编排上线加上Prometheus盯监控这条链路已经跑顺好几轮了。这篇文章把每一步的Prompt模板、配置文件、踩过的坑和排查心得全部整理出来适合正在做AI应用开发、智能体开发或者想把手上项目从零推到生产环境的工程师也适合刚入行、想了解AI开发全流程细节的朋友。跟着走一遍你就能理解什么叫“用AI的方式做AI开发”。1. 先想清楚再做需求规格说明书是提速的地基很多人一上来就急着让AI写代码结果需求本身是模糊的AI写得越快返工越狠。我自己最早也犯过这个错误拿一句话需求丢给AI生成的页面看着像模像样等到联调时候才发现字段对不上、状态流转缺环节、权限边界没定义。AI开发提效的前提是需求本身已经结构化。所以第一件事永远是输出一份需求规格说明书。1.1 为什么需求规格说明书这么重要需求规格说明书听起来很“传统”但它实际上是整个AI开发链路里最值得投资的一步。我见过太多项目死在“我以为你以为”上产品经理以为开发理解了业务开发以为AI理解了需求最后AI生成的代码跑起来业务却说这不是我要的。这不是AI能力不行而是输入太粗糙。一份合格的需求规格说明书至少要包含角色定义、业务流程、功能清单、数据字段、状态流转、权限规则、非功能需求。前六项决定功能对不对第七项决定能不能上线。比如AI商品推荐智能体如果需求文档里没写“推荐结果必须过滤下架商品”“冷启动用户按品类偏好兜底”AI生成的推荐逻辑大概率是裸的相似度计算上线后用户看到的推荐全是下架商品这锅只能开发背。用AI辅助写需求规格说明书是把“人脑里的模糊想象”转成“机器可读的清晰结构”。这一步不需要多复杂的技术本质上就是用一套高质量的Prompt模板让大模型帮你把碎片化需求梳理成结构化的规格文档。实测下来一份10页以内的需求规格说明书用AI辅助写通常一个小时内能出初稿人工再花半小时补充业务细节就够了。1.2 一套能直接复用的需求文档Prompt模板我将平时项目里最常用的Prompt模板贴出来。这套模板我用在不同规模的项目上AI生成的内容质量都还比较稳定。角色你是资深产品经理和技术架构师擅长将模糊需求转化为结构化的软件需求规格说明书。 任务请根据以下需求描述输出一份完整的软件需求规格说明书结构如下 一、项目概述 - 项目背景 - 项目目标需量化 - 目标用户与使用场景 二、角色与权限 - 系统涉及的角色 - 各角色的权限矩阵 三、业务流程 - 核心业务流程图用文字描述步骤 - 业务规则与约束 四、功能需求 - 每个功能模块需包含功能名称、功能描述、输入/输出、业务规则、异常处理 - 功能优先级标注P0必选P1重要P2可选 五、数据模型 - 核心数据实体 - 关键数据字段与类型 - 数据关系说明 六、接口需求 - 内部接口 - 外部依赖接口 - 接口错误码约定 七、非功能需求 - 性能并发量、响应时间定义 - 可用性目标可用性 - 安全权限校验、数据脱敏要求 需求描述如下 [粘贴你的原始需求描述] 输出要求 - 使用中文 - 面向开发人员术语准确 - 模糊信息处明确标注“需确认” - 不要省略任何模块这里有个关键技巧需求描述那块不要只写一句话把你能想到的碎片想法、参考截图里的文字说明、竞品观察到的功能点全部以列表形式贴进去。哪怕语句不通顺AI也能帮你提炼。输入信息越杂生成结果越细这个结论我在多个项目里验证过。1.3 把验收标准写进需求里后面能省两轮返工需求规格说明书里最容易漏掉的是“验收标准”。没有验收标准开发阶段AI生成的代码对不对你只能凭感觉判断。有了验收标准你可以直接把它翻译成代码审查清单甚至翻译成自动化测试用例。拿AI商品推荐智能体举例我在需求阶段就会写清楚这些验收项输入用户ID后推荐接口必须在500毫秒内返回结果推荐结果不得包含已下架商品每件商品必须附带推荐理由如“你常逛的XX品牌”连续刷新页面3次推荐结果不能完全重复新注册用户无行为数据必须走冷启动策略这些验收标准写进需求规格说明书里AI生成代码的时候会主动去满足这些约束比你事后测试再返工高效得多。另外我习惯把“非功能需求”单独做成一张表里面写清楚并发量预估、平均响应时间、可用性目标、数据保留周期后面做部署方案时直接拿出来对照不会出现“开发完了才发现服务器内存不够”这种尴尬。2. 从需求图片到代码用AI生成前后端项目骨架需求规格说明书定稿后真正的“AI开发提效”才刚开始。这一章节是大多数人最关心的怎么用AI根据需求图片直接生成前后端代码。过去做人要人肉翻译需求现在让AI做翻译。2.1 核心工具选型从Qoder到Workflow流式开发目前我用得最顺的主流程是先让AI根据需求图生成基础代码骨架再结合Workflow方式以“时间流”的思路逐步追加功能。所谓“时间流”的代码开发方式其实是别一上来就生成几千行完整代码而是把开发过程切成很多个时间片每片只做一个功能点前一个时间片的代码作为下一个时间片的上下文输入一步步把项目“养”出来。这样做有三个好处每一步的输入输出都可控代码出问题容易定位AI不需要一次记住太多上下文生成结果更稳定每个时间片之间可以进行代码审查发现错误及时止损工具方面我推荐写代码能力强的AI编辑器比如Qoder和同类对话式编程工具。它们都能理解图片输入可以直接把UI原型截图、需求图或者手绘草图丢进去AI识别出页面结构后生成前端代码后端部分则把接口定义、数据模型描述丢给它生成服务端代码。实测下来类似“按需求图片生成前后端代码”这种需求用Qoder这类工具能直接生成可运行的项目骨架。2.2 从需求图片生成前端代码的Prompt模板前端生成的Prompt模板我通常写成这样角色你是资深前端工程师擅长使用Vue 3 TypeScript Element Plus技术栈开发界面。 任务根据需求图片和说明生成完整可运行的前端页面代码。 界面要求 1. 页面布局与需求图片一致响应式适配 2. 颜色、字体、间距参考现代主流设计规范 3. 状态流转加载中/空数据/错误状态需处理 4. 图片中的静态数据全部替换为通过API获取的动态数据 技术约束 - 使用Vue 3 Composition API - 使用TypeScript - 使用Axios调用后端接口 - 接口返回格式约定{ code: 0, data: {...}, message: ok } 需求图片[在这里上传图片] 页面说明[补充图片里看不清的文字或交互逻辑]图片上传之后AI一般会识别图片里的布局结构生成对应的HTML/CSS/Vue代码。需要注意的是图片识别不是100%精准如果图片信息量太大建议把页面说明写得细一点比如“左上角是搜索栏右侧是用户信息卡片中间是推荐商品瀑布流”。这相当于给AI一幅“阅读理解提纲”。2.3 后端代码生成的Prompt模板与接口设计思路后端生成以接口为单位更实际。别让AI“生成整个后端系统”而是“生成某个接口的实现”这样准确性高很多我也强烈建议每个人养成这种拆解习惯。角色你是资深后端工程师负责开发一个[技术栈如Java Spring Boot / Python FastAPI]服务。 任务实现以下接口输出完整的Controller/Service/Mapper层代码、数据库DDL语句和接口文档。 接口需求 - 接口名称[如获取推荐商品列表] - 请求方式GET /api/recommend/products - 入参user_id, category_id, limit - 出参商品列表含商品ID、名称、图片、价格、推荐理由 - 核心业务逻辑 1. 优先读取Redis缓存缓存命中直接返回 2. 缓存未命中时调用推荐服务获取结果 3. 过滤已下架商品 4. 写入缓存并设置过期时间5分钟 5. 新用户无行为数据时走冷启动兜底逻辑 数据库设计 - 现有表products(id, name, image, price, status) - 需要新增的表/字段[描述你需要的] 额外要求 - 返回统一响应格式 - 参数校验齐全 - 异常处理完善 - 关键逻辑需补充注释后端接口设计是AI生成质量的关键。我的经验是接口粒度和业务规则描述得越清楚AI生成的代码越能直接用。如果业务规则有“必须先校验A再判断B”就明确写出来。如果你自己都没想清楚这个接口的前置条件和异常分支AI生成的东西大概率也是半吊子这一点和人工开发其实没有区别。2.4 实测生成后的必备检查清单AI生成的代码不能直接拿生产环境跑。这是底线。我每次生成完代码都会按这张清单快速检查一遍依赖版本是否合理AI生成时可能使用默认依赖但项目的Spring Boot版本或Node版本未必匹配数据库连接配置是否正确AI不知道你的库名、用户名、密码默认配置基本不可用权限控制是否缺失AI生成的管理后台页面默认可能不做权限拦截是否有硬编码IP地址、密钥、TokenAI生成代码容易出现接口错误码是否统一AI可能在不同方法里返回不同格式的异常这张清单看起来基础但我身边真正踩过坑的同事可不少。上个月我一同事让AI生成一个用户管理接口AI很贴心地生成了完整的增删改查但没做登录鉴权。代码一旦裸奔上线谁都能调删除接口。这种问题AI不会主动考虑“生产环境安全”只有你在Prompt里明确要求它才会跟着输出。3. 本地部署从Ollama到Dify的完整链路项目代码有了接下来要解决模型的问题。AI应用开发最核心的依赖就是大模型。现在很多团队的策略是先本地部署尤其涉及敏感数据、离线环境、成本控制的时候本地部署几乎是唯一选择。3.1 哪些场景必须本地部署我判断是否需要本地部署主要看三个因素第一是数据敏感性客户数据不能出内部网络这是合规硬线第二是成本如果调用外部API的量大月度成本可能比一台服务器还贵第三是稳定性外部API服务出现波动或者版本变更会影响应用可用性。本地部署主流方案里Ollama是个人和小团队的主流选择安装简单、模型管理方便Dify则是做AI应用编排的好帮手图形化地配置agent、工作流、知识库再搭配Ollama本地模型用起来很舒服ComfyUI主要跑图像生成工作流。这三件套基本覆盖了文本、Agent、图像三类常见场景。3.2 模型选型与量化配置为什么我关注flux-2-klein-9b选模型是个挺头痛的过程。参数太小效果差参数太大机器跑不动还要考虑量化格式对显存和推理速度的影响。我目前比较看重类似于flux-2-klein-9b这类9B级别的模型参数文件配置9B级模型量化后能在消费级显卡或者中等配置的推理服务器上流畅运行效果也比7B模型高一截显存需求相对可控。以flux-2-klein-9b的bf8量化配置为例说下我的处理思路。bf8是精度格式它的文件体积和显存占用比fp16更小推理速度更快而精度损失在大多数业务场景下几乎察觉不到。如果你也用类似规模的模型我建议重点关注3个配置项上下文长度默认往往偏低做复杂Agent任务时很容易“失忆”要按业务实际场景调大Batch Size会影响吞吐量并发高时调大但显存有限时不能盲目拉高量化精度显存紧张时选低精度追求效果时选高精度这份配置参数我记得写在了项目的config文件里包括并行线程数、缓存策略等。核心是先跑一个基准测试再看显存占用和推理延迟最后确定生产用的参数组合。别图省事全按默认配置默认配置往往只保证“能跑”不保证“跑得稳”。3.3 本地部署实操Ollama Dify组合本地部署Ollama很简单以下是我的完整操作流程。首先安装Ollama# Linux环境一条命令安装 curl -fsSL https://ollama.com/install.sh | sh # 验证安装 ollama --version # 拉取目标模型例如9B级别模型 ollama pull klein-9b # 测试模型是否正常工作 ollama run klein-9b 你好请简单介绍自己这里有个细节ollama run会开启一个交互式对话测试模型是否正常加载。生产环境我们一般不用这个命令而是启动服务# 设置Ollama服务监听地址允许其他机器访问 export OLLAMA_HOST0.0.0.0:11434 # 启动服务 ollama serve然后部署Dify。Dify支持Docker Compose方式安装官方会提供docker-compose.yml文件我习惯把它放到独立的目录里git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d等容器全部启动后浏览器访问服务器IP的80端口就能看到Dify控制台。在Dify里配置Ollama的连接类型选OllamaBase URL填http://你的Ollama主机IP:11434模型选刚才拉的klein-9b保存即可。这一步最容易出错的地方是Dify容器访问Ollama时不能用localhost因为Dify容器和Ollama服务是不同环境要用主机IP或者Docker网络内的服务名。我第一次配置的时候填localhost:11434结果一直报连接失败换了主机IP就通了。3.4 本地部署性能调优的小技巧本地部署追求的是在有限的硬件下挖掘最大潜力。我说几个实测有效但文档里很少提的做法给Ollama配置更长的超时时间模型加载需要较长时间默认超时可能不够推理时如果连续多轮对话速度变慢可能是上下文窗口被占满清理或适当压缩历史消息用SSD存放模型文件模型加载速度和首次响应速度都会明显提升这是性价比极高的硬件优化如果你有多张GPU可以设置CUDA_VISIBLE_DEVICES指定用哪张卡避免任务抢占另外生产环境一定要给模型设置“最大输出Token数”。AI模型一旦失控会无限输出下去既浪费资源又拖慢接口响应。我在Dify工作流里会把回应长度限制在合理范围内比如日志分析类的任务限制1000Token以内长文章创作才会放宽到3000。4. 生产部署Docker Compose和Prometheus监控的整合部署不是把服务跑起来就完了。真正的部署包含三个部分容器化编排、持续集成、监控告警。我平时最常用的部署组合是Docker Compose GitHub Actions Prometheus。4.1 用Docker Compose编排AI应用服务AI应用很少是只有一个服务的单体通常包含前端、后端、模型推理、向量数据库等组件。Docker Compose是维护这些服务最轻量的方式一个docker-compose.yml文件就能定义所有服务。我分享一个典型AI应用项目的Compose配置version: 3.8 services: backend: build: ./backend container_name: ai-backend ports: - 8080:8080 environment: - SPRING_PROFILES_ACTIVEprod - OLLAMA_HOSThttp://host.docker.internal:11434 - REDIS_HOSTredis depends_on: - redis - postgres restart: always frontend: build: ./frontend container_name: ai-frontend ports: - 80:80 depends_on: - backend redis: image: redis:7-alpine container_name: ai-redis volumes: - redis-data:/data restart: always postgres: image: postgres:15 container_name: ai-postgres environment: - POSTGRES_USERai_user - POSTGRES_PASSWORDchange_me - POSTGRES_DBai_app volumes: - postgres-data:/var/lib/postgresql/data restart: always prometheus: image: prom/prometheus container_name: ai-prometheus ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml restart: always grafana: image: grafana/grafana container_name: ai-grafana ports: - 3000:3000 volumes: - grafana-data:/var/lib/grafana restart: always volumes: redis-data: postgres-data: grafana-data:这个方法我用了很久几个关键点分享下一定要设置restart: always不然服务器一重启服务全挂了没人拉起密码不要直接写在Compose里生产环境使用环境变量文件.env前端一般通过Nginx容器托管静态文件并反向代理到后端多个容器之间的网络通信直接使用服务名互相访问不要写IP4.2 Prometheus Grafana监控到底要盯哪些指标很多项目上线后处于“裸奔”状态出了问题用户先发现大家才慌忙去日志里查。Prometheus的引入是为了把“被动救火”变成“主动预警”。我的Prometheus配置文件里通常做三件事采集基础主机指标、采集应用自定义指标、配置告警规则。global: scrape_interval: 15s scrape_configs: - job_name: node static_configs: - targets: [host.docker.internal:9100] - job_name: ai-backend metrics_path: /actuator/prometheus static_configs: - targets: [backend:8080] - job_name: ollama static_configs: - targets: [host.docker.internal:11434]对于AI应用下面几个指标一定要盯模型推理延迟P99延迟要在你的业务容忍范围内推荐请求P99达到2秒就需要优化模型推理并发数并发升高时是否触发了限流或排队容器CPU/内存用量内存泄漏往往以缓慢增长呈现通过监控曲线图能提前发现接口错误率5xx状态码比例超过1%需要报警队列积压量如果使用了消息队列积压量能反映消费能力是否足够还有一个容易忽略的指标是“模型Token输出量”。它不直接代表性能问题但能反映成本趋势。本地部署虽然没有API计费但Token输出量暴增意味着某个业务循环出了问题比如Agent在反复重试白白占用推理资源。4.3 用GitHub Actions把前后端自动部署到服务器有了Docker Compose和监控接下来就是CI/CD环节。比如我们把前端项目部署到GitHub Pages或者把后端Docker镜像推送到服务器并自动更新服务。这一块我用的是流水线核心逻辑是代码推送到主分支时自动触发构建、测试、部署。我分享一个用GitHub Actions自动构建后端镜像并部署到服务器的Pipelinename: Deploy AI Backend on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv3 - name: Build Docker image run: | docker build -t my-registry/ai-backend:latest ./backend - name: Push to registry env: REGISTRY_USER: ${{ secrets.REGISTRY_USER }} REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }} run: | docker login my-registry.example.com -u $REGISTRY_USER -p $REGISTRY_PASSWORD docker push my-registry/ai-backend:latest - name: Deploy to server env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} SERVER_IP: ${{ secrets.SERVER_IP }} run: | echo $SSH_PRIVATE_KEY deploy_key chmod 600 deploy_key ssh -i deploy_key ubuntu$SERVER_IP cd /opt/ai-project docker compose pull backend docker compose up -d backend一个在维护中很重要的细节尽量使用带有唯一标签的镜像而不是永远用latest。latest标签在回滚时特别不方便你不知道当前线上跑的是哪个版本。我现在的做法是使用Git提交的SHA作为镜像标签比如ai-backend:a1b2c3d并且把它写入部署时的环境变量里这样一旦出问题可以直接回滚到上一个SHA。4.4 经典实践把个人博客或文档站部署到GitHub Pages很多AI应用项目还会配套一个文档站或者干脆就是个静态博客。静态站点部署到GitHub Pages是免费且稳定的方案Hexo是我一直在用的工具。Hexo部署到GitHub Pages核心操作是# 安装Hexo npm install hexo-cli -g # 初始化项目 hexo init my-blog cd my-blog npm install # 安装部署插件 npm install hexo-deployer-git --save # 在_config.yml中配置deploy信息 deploy: type: git repo: gitgithub.com:你的用户名/你的用户名.github.io.git branch: main # 生成静态文件并部署 hexo g hexo d这里有个经验如果你用GitHub Actions做自动部署就不需要在本地安装SSH密钥Actions容器里配置好仓库的Secrets推送代码时自动执行hexo g hexo d流程更规范。文档站和博客建议内置一个版本号信息页每次自动部署后页面底部的版本号会自动更新方便跟用户确认“你看到的是不是最新版”。5. 常见问题与排查技巧实录最后这部分我把从需求到部署过程中遇到的高频问题整理成一份速查表。这些问题我基本都实际踩过或者帮同事排查过每个都是真实的血泪经验。5.1 需求阶段AI生成的需求文档“太泛”现象是AI生成的需求规格说明书内容看起来完整但缺少业务灵魂比如“支持用户管理”这种描述根本没有说清楚什么角色能新增、什么角色能删除、删除时要不要做数据转移。排查思路模板里增加“场景驱动”的描述要求明确在Prompt中要求输出至少3个典型使用场景同时补充“边界与例外”小节比如“同一商品不能推荐两次”“库存不足时不展示”AI生成的结果才会往深里走。我现在的习惯是在需求Prompt模板后面固定加一句如果业务规则不明确请列出3个关键问题指定给业务方确认。这样AI会主动标注出模糊点而不是含糊地跳过去。5.2 代码生成阶段AI生成的前后端代码对不上接口现象前端页面调后端接口时字段名对不上、应答格式不同、接口路径多了前缀。根因前后端代码是分两次生成的AI没有共享同一份接口定义。这就像两个开发分别闷头写代码却没有一起对接口文档。解决办法在生成前后端代码之前先让AI生成一份OpenAPI规范的接口定义文档。后端按文档实现接口前端按文档模拟接口两边都以这份文档为准。我实测过这样前后端联调问题可以减少80%以上。另外生成后端代码时我会直接把接口定义文件的JSON文件粘贴给AI让它在实现时严格遵循。生成前端代码时同样把这JSON文件粘贴进去让AI按接口定义写API调用层。双重约束下代码合不上路径或者字段错位的情况就会少很多。5.3 本地部署Ollama模型加载慢或显存溢出的处理现象1模型加载时间很长首次请求要等几十秒。 原因模型文件没有缓存到内存或者磁盘读取慢。 解决把模型文件放到SSD设置OLLAMA_KEEP_ALIVE为较长的时间保持模型常驻内存。现象2启动服务后程序崩溃提示CUDA out of memory。 原因显存不够运行当前模型和上下文窗口。 解决换更小体积的量化版本缩短上下文长度配置降低batch size如果服务端是CPU/GPU混合环境考虑只使用GPU推理。有一个检查显存占用的小技巧在Linux里用nvidia-smi实时查看进程显存占用。如果显存占用在波动说明模型还在加载或上下文在动态分配这时候要多给它一些时间不急着下结论说“模型卡死”。5.4 Docker部署容器间网络连不上现象后端容器调用Ollama失败报connection refused或getaddrinfo EAI_AGAIN。排查思路先用docker compose ps确认目标容器是否正常启动再用docker compose exec backend curl http://ollama:11434测试容器间网络如果容器间不通检查docker-compose.yml里是否定义了同一个network如果调用的是宿主机上的服务用host.docker.internal代替127.0.0.1这里最坑的是Windows/Mac的Docker Desktop和Linux Docker对host.docker.internal的支持不一致。Linux默认不支持需要加extra_hosts: - host.docker.internal:host-gateway。第一次在Linux服务器部署时我为了这个问题折腾了一个多小时。5.5 Prometheus监控报警风暴的处理现象一次发布后报警持续刷屏全是“容器CPU使用率超过80%”。排查与处理思路先到Grafana看趋势图确认是全量告警还是特定服务告警如果是特定服务检查该服务的代码是否有死循环或者连接泄漏如果确实是全量增长检查是不是发布时存在“缓存预热”或者“模型重新加载”的短期行为针对可控的短期波动在Prometheus告警规则里设置for: 5m条件只有持续5分钟才触发告警能有效过滤瞬时尖峰Prometheus告警规则我强烈建议在部署完成后就配置好不要等服务真正告警了再临时加规则。5.6 部署回滚方案没有人能保证自己每次部署都成功。一定要提前准备回滚方案不要临时想办法。我的回滚策略很简单后端镜像直接用版本号的tagGit SHA回滚时修改tag重新部署前端用的是Nginx静态资源回滚时重新发布上一个版本的构建产物数据库结构变更要有独立的迁移脚本必要时可以执行反向迁移所有回滚步骤写进文档并且至少走一遍演练很多团队出大事都是因为“回滚没演练过”真出事时手忙脚乱。只要回滚方案是现成的、演练过的部署就不会让人焦虑。现在这个项目的后续扩展我会把重点放在两件事上一是把需求阶段的Prompt模板沉淀成团队通用资产新项目直接复用二是把模型推理的监控指标接入到告警面板让模型服务的健康状态可视化而不是出了问题再翻日志。另外想给做AI应用开发的朋友一个建议不要总想着一次搞定所有智能体功能先从最核心的一条主路径跑通上线之后再迭代。这个思路听起来普通但真正能压缩你项目交付周期的地方往往就在这里。 AI应用开发全流程提效实战：从需求到部署的完整指南
很多事情不真正跑到生产环境你是不知道水有多深的。上个月我带团队做AI商品推荐智能体从接到需求到部署上线整个周期比原计划缩短了接近10倍。以前这套流程少说两三周需求反复对齐、技术方案评审、接口联调、部署配置、监控告警每一步都能卡住人。现在从需求规格说明书开始到用AI生成前后端代码再到本地部署大模型、用Docker Compose编排上线加上Prometheus盯监控这条链路已经跑顺好几轮了。这篇文章把每一步的Prompt模板、配置文件、踩过的坑和排查心得全部整理出来适合正在做AI应用开发、智能体开发或者想把手上项目从零推到生产环境的工程师也适合刚入行、想了解AI开发全流程细节的朋友。跟着走一遍你就能理解什么叫“用AI的方式做AI开发”。1. 先想清楚再做需求规格说明书是提速的地基很多人一上来就急着让AI写代码结果需求本身是模糊的AI写得越快返工越狠。我自己最早也犯过这个错误拿一句话需求丢给AI生成的页面看着像模像样等到联调时候才发现字段对不上、状态流转缺环节、权限边界没定义。AI开发提效的前提是需求本身已经结构化。所以第一件事永远是输出一份需求规格说明书。1.1 为什么需求规格说明书这么重要需求规格说明书听起来很“传统”但它实际上是整个AI开发链路里最值得投资的一步。我见过太多项目死在“我以为你以为”上产品经理以为开发理解了业务开发以为AI理解了需求最后AI生成的代码跑起来业务却说这不是我要的。这不是AI能力不行而是输入太粗糙。一份合格的需求规格说明书至少要包含角色定义、业务流程、功能清单、数据字段、状态流转、权限规则、非功能需求。前六项决定功能对不对第七项决定能不能上线。比如AI商品推荐智能体如果需求文档里没写“推荐结果必须过滤下架商品”“冷启动用户按品类偏好兜底”AI生成的推荐逻辑大概率是裸的相似度计算上线后用户看到的推荐全是下架商品这锅只能开发背。用AI辅助写需求规格说明书是把“人脑里的模糊想象”转成“机器可读的清晰结构”。这一步不需要多复杂的技术本质上就是用一套高质量的Prompt模板让大模型帮你把碎片化需求梳理成结构化的规格文档。实测下来一份10页以内的需求规格说明书用AI辅助写通常一个小时内能出初稿人工再花半小时补充业务细节就够了。1.2 一套能直接复用的需求文档Prompt模板我将平时项目里最常用的Prompt模板贴出来。这套模板我用在不同规模的项目上AI生成的内容质量都还比较稳定。角色你是资深产品经理和技术架构师擅长将模糊需求转化为结构化的软件需求规格说明书。 任务请根据以下需求描述输出一份完整的软件需求规格说明书结构如下 一、项目概述 - 项目背景 - 项目目标需量化 - 目标用户与使用场景 二、角色与权限 - 系统涉及的角色 - 各角色的权限矩阵 三、业务流程 - 核心业务流程图用文字描述步骤 - 业务规则与约束 四、功能需求 - 每个功能模块需包含功能名称、功能描述、输入/输出、业务规则、异常处理 - 功能优先级标注P0必选P1重要P2可选 五、数据模型 - 核心数据实体 - 关键数据字段与类型 - 数据关系说明 六、接口需求 - 内部接口 - 外部依赖接口 - 接口错误码约定 七、非功能需求 - 性能并发量、响应时间定义 - 可用性目标可用性 - 安全权限校验、数据脱敏要求 需求描述如下 [粘贴你的原始需求描述] 输出要求 - 使用中文 - 面向开发人员术语准确 - 模糊信息处明确标注“需确认” - 不要省略任何模块这里有个关键技巧需求描述那块不要只写一句话把你能想到的碎片想法、参考截图里的文字说明、竞品观察到的功能点全部以列表形式贴进去。哪怕语句不通顺AI也能帮你提炼。输入信息越杂生成结果越细这个结论我在多个项目里验证过。1.3 把验收标准写进需求里后面能省两轮返工需求规格说明书里最容易漏掉的是“验收标准”。没有验收标准开发阶段AI生成的代码对不对你只能凭感觉判断。有了验收标准你可以直接把它翻译成代码审查清单甚至翻译成自动化测试用例。拿AI商品推荐智能体举例我在需求阶段就会写清楚这些验收项输入用户ID后推荐接口必须在500毫秒内返回结果推荐结果不得包含已下架商品每件商品必须附带推荐理由如“你常逛的XX品牌”连续刷新页面3次推荐结果不能完全重复新注册用户无行为数据必须走冷启动策略这些验收标准写进需求规格说明书里AI生成代码的时候会主动去满足这些约束比你事后测试再返工高效得多。另外我习惯把“非功能需求”单独做成一张表里面写清楚并发量预估、平均响应时间、可用性目标、数据保留周期后面做部署方案时直接拿出来对照不会出现“开发完了才发现服务器内存不够”这种尴尬。2. 从需求图片到代码用AI生成前后端项目骨架需求规格说明书定稿后真正的“AI开发提效”才刚开始。这一章节是大多数人最关心的怎么用AI根据需求图片直接生成前后端代码。过去做人要人肉翻译需求现在让AI做翻译。2.1 核心工具选型从Qoder到Workflow流式开发目前我用得最顺的主流程是先让AI根据需求图生成基础代码骨架再结合Workflow方式以“时间流”的思路逐步追加功能。所谓“时间流”的代码开发方式其实是别一上来就生成几千行完整代码而是把开发过程切成很多个时间片每片只做一个功能点前一个时间片的代码作为下一个时间片的上下文输入一步步把项目“养”出来。这样做有三个好处每一步的输入输出都可控代码出问题容易定位AI不需要一次记住太多上下文生成结果更稳定每个时间片之间可以进行代码审查发现错误及时止损工具方面我推荐写代码能力强的AI编辑器比如Qoder和同类对话式编程工具。它们都能理解图片输入可以直接把UI原型截图、需求图或者手绘草图丢进去AI识别出页面结构后生成前端代码后端部分则把接口定义、数据模型描述丢给它生成服务端代码。实测下来类似“按需求图片生成前后端代码”这种需求用Qoder这类工具能直接生成可运行的项目骨架。2.2 从需求图片生成前端代码的Prompt模板前端生成的Prompt模板我通常写成这样角色你是资深前端工程师擅长使用Vue 3 TypeScript Element Plus技术栈开发界面。 任务根据需求图片和说明生成完整可运行的前端页面代码。 界面要求 1. 页面布局与需求图片一致响应式适配 2. 颜色、字体、间距参考现代主流设计规范 3. 状态流转加载中/空数据/错误状态需处理 4. 图片中的静态数据全部替换为通过API获取的动态数据 技术约束 - 使用Vue 3 Composition API - 使用TypeScript - 使用Axios调用后端接口 - 接口返回格式约定{ code: 0, data: {...}, message: ok } 需求图片[在这里上传图片] 页面说明[补充图片里看不清的文字或交互逻辑]图片上传之后AI一般会识别图片里的布局结构生成对应的HTML/CSS/Vue代码。需要注意的是图片识别不是100%精准如果图片信息量太大建议把页面说明写得细一点比如“左上角是搜索栏右侧是用户信息卡片中间是推荐商品瀑布流”。这相当于给AI一幅“阅读理解提纲”。2.3 后端代码生成的Prompt模板与接口设计思路后端生成以接口为单位更实际。别让AI“生成整个后端系统”而是“生成某个接口的实现”这样准确性高很多我也强烈建议每个人养成这种拆解习惯。角色你是资深后端工程师负责开发一个[技术栈如Java Spring Boot / Python FastAPI]服务。 任务实现以下接口输出完整的Controller/Service/Mapper层代码、数据库DDL语句和接口文档。 接口需求 - 接口名称[如获取推荐商品列表] - 请求方式GET /api/recommend/products - 入参user_id, category_id, limit - 出参商品列表含商品ID、名称、图片、价格、推荐理由 - 核心业务逻辑 1. 优先读取Redis缓存缓存命中直接返回 2. 缓存未命中时调用推荐服务获取结果 3. 过滤已下架商品 4. 写入缓存并设置过期时间5分钟 5. 新用户无行为数据时走冷启动兜底逻辑 数据库设计 - 现有表products(id, name, image, price, status) - 需要新增的表/字段[描述你需要的] 额外要求 - 返回统一响应格式 - 参数校验齐全 - 异常处理完善 - 关键逻辑需补充注释后端接口设计是AI生成质量的关键。我的经验是接口粒度和业务规则描述得越清楚AI生成的代码越能直接用。如果业务规则有“必须先校验A再判断B”就明确写出来。如果你自己都没想清楚这个接口的前置条件和异常分支AI生成的东西大概率也是半吊子这一点和人工开发其实没有区别。2.4 实测生成后的必备检查清单AI生成的代码不能直接拿生产环境跑。这是底线。我每次生成完代码都会按这张清单快速检查一遍依赖版本是否合理AI生成时可能使用默认依赖但项目的Spring Boot版本或Node版本未必匹配数据库连接配置是否正确AI不知道你的库名、用户名、密码默认配置基本不可用权限控制是否缺失AI生成的管理后台页面默认可能不做权限拦截是否有硬编码IP地址、密钥、TokenAI生成代码容易出现接口错误码是否统一AI可能在不同方法里返回不同格式的异常这张清单看起来基础但我身边真正踩过坑的同事可不少。上个月我一同事让AI生成一个用户管理接口AI很贴心地生成了完整的增删改查但没做登录鉴权。代码一旦裸奔上线谁都能调删除接口。这种问题AI不会主动考虑“生产环境安全”只有你在Prompt里明确要求它才会跟着输出。3. 本地部署从Ollama到Dify的完整链路项目代码有了接下来要解决模型的问题。AI应用开发最核心的依赖就是大模型。现在很多团队的策略是先本地部署尤其涉及敏感数据、离线环境、成本控制的时候本地部署几乎是唯一选择。3.1 哪些场景必须本地部署我判断是否需要本地部署主要看三个因素第一是数据敏感性客户数据不能出内部网络这是合规硬线第二是成本如果调用外部API的量大月度成本可能比一台服务器还贵第三是稳定性外部API服务出现波动或者版本变更会影响应用可用性。本地部署主流方案里Ollama是个人和小团队的主流选择安装简单、模型管理方便Dify则是做AI应用编排的好帮手图形化地配置agent、工作流、知识库再搭配Ollama本地模型用起来很舒服ComfyUI主要跑图像生成工作流。这三件套基本覆盖了文本、Agent、图像三类常见场景。3.2 模型选型与量化配置为什么我关注flux-2-klein-9b选模型是个挺头痛的过程。参数太小效果差参数太大机器跑不动还要考虑量化格式对显存和推理速度的影响。我目前比较看重类似于flux-2-klein-9b这类9B级别的模型参数文件配置9B级模型量化后能在消费级显卡或者中等配置的推理服务器上流畅运行效果也比7B模型高一截显存需求相对可控。以flux-2-klein-9b的bf8量化配置为例说下我的处理思路。bf8是精度格式它的文件体积和显存占用比fp16更小推理速度更快而精度损失在大多数业务场景下几乎察觉不到。如果你也用类似规模的模型我建议重点关注3个配置项上下文长度默认往往偏低做复杂Agent任务时很容易“失忆”要按业务实际场景调大Batch Size会影响吞吐量并发高时调大但显存有限时不能盲目拉高量化精度显存紧张时选低精度追求效果时选高精度这份配置参数我记得写在了项目的config文件里包括并行线程数、缓存策略等。核心是先跑一个基准测试再看显存占用和推理延迟最后确定生产用的参数组合。别图省事全按默认配置默认配置往往只保证“能跑”不保证“跑得稳”。3.3 本地部署实操Ollama Dify组合本地部署Ollama很简单以下是我的完整操作流程。首先安装Ollama# Linux环境一条命令安装 curl -fsSL https://ollama.com/install.sh | sh # 验证安装 ollama --version # 拉取目标模型例如9B级别模型 ollama pull klein-9b # 测试模型是否正常工作 ollama run klein-9b 你好请简单介绍自己这里有个细节ollama run会开启一个交互式对话测试模型是否正常加载。生产环境我们一般不用这个命令而是启动服务# 设置Ollama服务监听地址允许其他机器访问 export OLLAMA_HOST0.0.0.0:11434 # 启动服务 ollama serve然后部署Dify。Dify支持Docker Compose方式安装官方会提供docker-compose.yml文件我习惯把它放到独立的目录里git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d等容器全部启动后浏览器访问服务器IP的80端口就能看到Dify控制台。在Dify里配置Ollama的连接类型选OllamaBase URL填http://你的Ollama主机IP:11434模型选刚才拉的klein-9b保存即可。这一步最容易出错的地方是Dify容器访问Ollama时不能用localhost因为Dify容器和Ollama服务是不同环境要用主机IP或者Docker网络内的服务名。我第一次配置的时候填localhost:11434结果一直报连接失败换了主机IP就通了。3.4 本地部署性能调优的小技巧本地部署追求的是在有限的硬件下挖掘最大潜力。我说几个实测有效但文档里很少提的做法给Ollama配置更长的超时时间模型加载需要较长时间默认超时可能不够推理时如果连续多轮对话速度变慢可能是上下文窗口被占满清理或适当压缩历史消息用SSD存放模型文件模型加载速度和首次响应速度都会明显提升这是性价比极高的硬件优化如果你有多张GPU可以设置CUDA_VISIBLE_DEVICES指定用哪张卡避免任务抢占另外生产环境一定要给模型设置“最大输出Token数”。AI模型一旦失控会无限输出下去既浪费资源又拖慢接口响应。我在Dify工作流里会把回应长度限制在合理范围内比如日志分析类的任务限制1000Token以内长文章创作才会放宽到3000。4. 生产部署Docker Compose和Prometheus监控的整合部署不是把服务跑起来就完了。真正的部署包含三个部分容器化编排、持续集成、监控告警。我平时最常用的部署组合是Docker Compose GitHub Actions Prometheus。4.1 用Docker Compose编排AI应用服务AI应用很少是只有一个服务的单体通常包含前端、后端、模型推理、向量数据库等组件。Docker Compose是维护这些服务最轻量的方式一个docker-compose.yml文件就能定义所有服务。我分享一个典型AI应用项目的Compose配置version: 3.8 services: backend: build: ./backend container_name: ai-backend ports: - 8080:8080 environment: - SPRING_PROFILES_ACTIVEprod - OLLAMA_HOSThttp://host.docker.internal:11434 - REDIS_HOSTredis depends_on: - redis - postgres restart: always frontend: build: ./frontend container_name: ai-frontend ports: - 80:80 depends_on: - backend redis: image: redis:7-alpine container_name: ai-redis volumes: - redis-data:/data restart: always postgres: image: postgres:15 container_name: ai-postgres environment: - POSTGRES_USERai_user - POSTGRES_PASSWORDchange_me - POSTGRES_DBai_app volumes: - postgres-data:/var/lib/postgresql/data restart: always prometheus: image: prom/prometheus container_name: ai-prometheus ports: - 9090:9090 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml restart: always grafana: image: grafana/grafana container_name: ai-grafana ports: - 3000:3000 volumes: - grafana-data:/var/lib/grafana restart: always volumes: redis-data: postgres-data: grafana-data:这个方法我用了很久几个关键点分享下一定要设置restart: always不然服务器一重启服务全挂了没人拉起密码不要直接写在Compose里生产环境使用环境变量文件.env前端一般通过Nginx容器托管静态文件并反向代理到后端多个容器之间的网络通信直接使用服务名互相访问不要写IP4.2 Prometheus Grafana监控到底要盯哪些指标很多项目上线后处于“裸奔”状态出了问题用户先发现大家才慌忙去日志里查。Prometheus的引入是为了把“被动救火”变成“主动预警”。我的Prometheus配置文件里通常做三件事采集基础主机指标、采集应用自定义指标、配置告警规则。global: scrape_interval: 15s scrape_configs: - job_name: node static_configs: - targets: [host.docker.internal:9100] - job_name: ai-backend metrics_path: /actuator/prometheus static_configs: - targets: [backend:8080] - job_name: ollama static_configs: - targets: [host.docker.internal:11434]对于AI应用下面几个指标一定要盯模型推理延迟P99延迟要在你的业务容忍范围内推荐请求P99达到2秒就需要优化模型推理并发数并发升高时是否触发了限流或排队容器CPU/内存用量内存泄漏往往以缓慢增长呈现通过监控曲线图能提前发现接口错误率5xx状态码比例超过1%需要报警队列积压量如果使用了消息队列积压量能反映消费能力是否足够还有一个容易忽略的指标是“模型Token输出量”。它不直接代表性能问题但能反映成本趋势。本地部署虽然没有API计费但Token输出量暴增意味着某个业务循环出了问题比如Agent在反复重试白白占用推理资源。4.3 用GitHub Actions把前后端自动部署到服务器有了Docker Compose和监控接下来就是CI/CD环节。比如我们把前端项目部署到GitHub Pages或者把后端Docker镜像推送到服务器并自动更新服务。这一块我用的是流水线核心逻辑是代码推送到主分支时自动触发构建、测试、部署。我分享一个用GitHub Actions自动构建后端镜像并部署到服务器的Pipelinename: Deploy AI Backend on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv3 - name: Build Docker image run: | docker build -t my-registry/ai-backend:latest ./backend - name: Push to registry env: REGISTRY_USER: ${{ secrets.REGISTRY_USER }} REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }} run: | docker login my-registry.example.com -u $REGISTRY_USER -p $REGISTRY_PASSWORD docker push my-registry/ai-backend:latest - name: Deploy to server env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} SERVER_IP: ${{ secrets.SERVER_IP }} run: | echo $SSH_PRIVATE_KEY deploy_key chmod 600 deploy_key ssh -i deploy_key ubuntu$SERVER_IP cd /opt/ai-project docker compose pull backend docker compose up -d backend一个在维护中很重要的细节尽量使用带有唯一标签的镜像而不是永远用latest。latest标签在回滚时特别不方便你不知道当前线上跑的是哪个版本。我现在的做法是使用Git提交的SHA作为镜像标签比如ai-backend:a1b2c3d并且把它写入部署时的环境变量里这样一旦出问题可以直接回滚到上一个SHA。4.4 经典实践把个人博客或文档站部署到GitHub Pages很多AI应用项目还会配套一个文档站或者干脆就是个静态博客。静态站点部署到GitHub Pages是免费且稳定的方案Hexo是我一直在用的工具。Hexo部署到GitHub Pages核心操作是# 安装Hexo npm install hexo-cli -g # 初始化项目 hexo init my-blog cd my-blog npm install # 安装部署插件 npm install hexo-deployer-git --save # 在_config.yml中配置deploy信息 deploy: type: git repo: gitgithub.com:你的用户名/你的用户名.github.io.git branch: main # 生成静态文件并部署 hexo g hexo d这里有个经验如果你用GitHub Actions做自动部署就不需要在本地安装SSH密钥Actions容器里配置好仓库的Secrets推送代码时自动执行hexo g hexo d流程更规范。文档站和博客建议内置一个版本号信息页每次自动部署后页面底部的版本号会自动更新方便跟用户确认“你看到的是不是最新版”。5. 常见问题与排查技巧实录最后这部分我把从需求到部署过程中遇到的高频问题整理成一份速查表。这些问题我基本都实际踩过或者帮同事排查过每个都是真实的血泪经验。5.1 需求阶段AI生成的需求文档“太泛”现象是AI生成的需求规格说明书内容看起来完整但缺少业务灵魂比如“支持用户管理”这种描述根本没有说清楚什么角色能新增、什么角色能删除、删除时要不要做数据转移。排查思路模板里增加“场景驱动”的描述要求明确在Prompt中要求输出至少3个典型使用场景同时补充“边界与例外”小节比如“同一商品不能推荐两次”“库存不足时不展示”AI生成的结果才会往深里走。我现在的习惯是在需求Prompt模板后面固定加一句如果业务规则不明确请列出3个关键问题指定给业务方确认。这样AI会主动标注出模糊点而不是含糊地跳过去。5.2 代码生成阶段AI生成的前后端代码对不上接口现象前端页面调后端接口时字段名对不上、应答格式不同、接口路径多了前缀。根因前后端代码是分两次生成的AI没有共享同一份接口定义。这就像两个开发分别闷头写代码却没有一起对接口文档。解决办法在生成前后端代码之前先让AI生成一份OpenAPI规范的接口定义文档。后端按文档实现接口前端按文档模拟接口两边都以这份文档为准。我实测过这样前后端联调问题可以减少80%以上。另外生成后端代码时我会直接把接口定义文件的JSON文件粘贴给AI让它在实现时严格遵循。生成前端代码时同样把这JSON文件粘贴进去让AI按接口定义写API调用层。双重约束下代码合不上路径或者字段错位的情况就会少很多。5.3 本地部署Ollama模型加载慢或显存溢出的处理现象1模型加载时间很长首次请求要等几十秒。 原因模型文件没有缓存到内存或者磁盘读取慢。 解决把模型文件放到SSD设置OLLAMA_KEEP_ALIVE为较长的时间保持模型常驻内存。现象2启动服务后程序崩溃提示CUDA out of memory。 原因显存不够运行当前模型和上下文窗口。 解决换更小体积的量化版本缩短上下文长度配置降低batch size如果服务端是CPU/GPU混合环境考虑只使用GPU推理。有一个检查显存占用的小技巧在Linux里用nvidia-smi实时查看进程显存占用。如果显存占用在波动说明模型还在加载或上下文在动态分配这时候要多给它一些时间不急着下结论说“模型卡死”。5.4 Docker部署容器间网络连不上现象后端容器调用Ollama失败报connection refused或getaddrinfo EAI_AGAIN。排查思路先用docker compose ps确认目标容器是否正常启动再用docker compose exec backend curl http://ollama:11434测试容器间网络如果容器间不通检查docker-compose.yml里是否定义了同一个network如果调用的是宿主机上的服务用host.docker.internal代替127.0.0.1这里最坑的是Windows/Mac的Docker Desktop和Linux Docker对host.docker.internal的支持不一致。Linux默认不支持需要加extra_hosts: - host.docker.internal:host-gateway。第一次在Linux服务器部署时我为了这个问题折腾了一个多小时。5.5 Prometheus监控报警风暴的处理现象一次发布后报警持续刷屏全是“容器CPU使用率超过80%”。排查与处理思路先到Grafana看趋势图确认是全量告警还是特定服务告警如果是特定服务检查该服务的代码是否有死循环或者连接泄漏如果确实是全量增长检查是不是发布时存在“缓存预热”或者“模型重新加载”的短期行为针对可控的短期波动在Prometheus告警规则里设置for: 5m条件只有持续5分钟才触发告警能有效过滤瞬时尖峰Prometheus告警规则我强烈建议在部署完成后就配置好不要等服务真正告警了再临时加规则。5.6 部署回滚方案没有人能保证自己每次部署都成功。一定要提前准备回滚方案不要临时想办法。我的回滚策略很简单后端镜像直接用版本号的tagGit SHA回滚时修改tag重新部署前端用的是Nginx静态资源回滚时重新发布上一个版本的构建产物数据库结构变更要有独立的迁移脚本必要时可以执行反向迁移所有回滚步骤写进文档并且至少走一遍演练很多团队出大事都是因为“回滚没演练过”真出事时手忙脚乱。只要回滚方案是现成的、演练过的部署就不会让人焦虑。现在这个项目的后续扩展我会把重点放在两件事上一是把需求阶段的Prompt模板沉淀成团队通用资产新项目直接复用二是把模型推理的监控指标接入到告警面板让模型服务的健康状态可视化而不是出了问题再翻日志。另外想给做AI应用开发的朋友一个建议不要总想着一次搞定所有智能体功能先从最核心的一条主路径跑通上线之后再迭代。这个思路听起来普通但真正能压缩你项目交付周期的地方往往就在这里。