AI辅助从零搭建文档摘要API：FastAPI与大模型调用实战-北京尧图网络

最近在整理手头的工具项目时我发现自己卡在同一个环节想法早就有了但一提服务端开发就打怵。路由、鉴权、部署、环境变量……每个词都像一堵墙。后来我换了个思路——既然大模型写代码的能力已经够用为什么不让 AI 帮我从零把 API 服务搭起来这篇就是这个过程的完整记录。我用 AI 从零搭了一个文档摘要 API输入任意长度的文本它调用大模型接口帮你提炼重点对外暴露一个标准 HTTP 接口。整个开发过程不依赖任何现成脚手架从新建项目目录到写代码、调 bug、做 Docker 镜像、上线部署全部由 AI 辅助完成。这篇文章适合那些想快速把想法变成可用接口、但服务端经验还不多的开发者如果你已经写过不少接口也可以重点看后面如何用 AI 做需求拆解和排错的部分这部分可能是你日常 Copilot 用得最少、价值最高的能力。1. 先定目标要搭的 API 到底长什么样动手写代码之前我得先把自己的需求想清楚。很多 AI 写代码失败的案例根源不是 AI 不行而是提需求的人自己都没想明白要做什么。1.1 项目定位做一个文档摘要 API我选的练手项目是文档摘要用户通过 POST 请求提交一段文本比如一篇文章、会议纪要、产品说明服务端把文本发给大模型让它生成一段 200 字以内的摘要再把结果以 JSON 格式返回给调用方。为什么选这个项目原因有三第一功能边界清晰一个请求进、一个结果出没有复杂的业务状态第二它必然涉及真实的大模型 API 调用能把如何安全地管理密钥如何处理上游超时如何设计错误响应这些服务端硬功夫全部练到第三摘要类任务是当前大模型最稳定的能力之一翻车概率低适合当第一个从零到上线的项目。1.2 对外接口的语义约定我在让 AI 写代码之前自己先拟了一份接口语义。这一步很多人跳过了直接说帮我写一个 APIAI 往往只能回一个空壳。我定义了两个接口接口请求方法请求体成功响应失败响应/healthGET无{status: ok}无/summarizePOST{text: 需要摘要的长文本, max_length: 200}{summary: 生成出的摘要}4xx/5xx 错误这里有一个容易被忽略的点max_length是客户端可选的参数但我给它的语义是摘要长度上限而不是要求模型输出恰好这么多字。大模型输出的 token 数是概率性的你不能像调函数一样精确控制字数所以把语义定为上限而不是精确值后续测试不容易被 AI 的偷懒气到。1.3 为什么选 FastAPI 而不是 Flask 或 Express选型是让 AI 替你写代码前少数必须自己拍板的事情。我直接用 FastAPI理由有两条。第一FastAPI 的自动 API 文档体验对新手极其友好启动服务后浏览器访问/docs就能看到交互式调试页面不用自己手动拼 curl 命令去验证接口。这个特性在 AI 生成代码的场景下特别值钱——AI 写的路由到底通不通打开/docs一目了然。第二FastAPI 原生的pydantic模型可以做请求体校验。AI 生成的代码里最容易出现的问题就是参数取用不规范比如request.body[text]写成request.json[text]而 FastAPI 的依赖注入机制能从根源上减少这类错误。2. AI 协作工具的选型不是越贵越好是越顺手越好这篇文章标题叫用 AI 搭 API 服务但用 AI本身也要先解决工具问题。我用的是大模型 API 编程插件对话式 IDE三层组合每层都有明确的用途边界。2.1 承担结对程序员角色的大模型选择辅助写代码的大模型我的核心要求不是聪明而是便宜、稳定、上下文够长。目前国内可直接调用的几个大模型 API 都很成熟比如 DeepSeek 的对话模型、智谱的 GLM 系列、阿里云的通义千问系列它们都有面向开发者的 API 网关注册后可以拿到 Key免费额度也足够完成这种体量的小项目。我这次主力用的是 DeepSeek 的对话模型。原因不是它一定比其他家强而是它的 API 格式和 OpenAI 协议完全兼容后续如果想把服务改造成兼容多模型路由代码改动成本最低。检索资料时大家也会看到很多免费大模型 API汇总我的建议是别贪多先固定一个主模型把链路跑通之后想加多模型支持那是第二个迭代周期的事。2.2 辅助编程插件的搭配方式除了在对话界面里问 AI我还装了 AI 编程插件比如 PyCharm 生态里常见的 Fitten Code 一类。它的价值不在自动写代码而在两件事局部的选中这段代码解释一下、报错后把光标放在红波浪线上问它这里为什么报错。这类插件使用的时候要注意上下文长度如果你选中一个几百行的大文件往里塞很容易触发模型上下文超限报错效率反而下降。我的搭配经验是全局规划问对话式 AI比如怎么设计接口、怎么拆模块局部实现问 IDE 插件这一行为什么报错、这个函数签名是什么意思。两层各司其职不要混用。2.3 为什么我不建议上来就上全自动 Agent现在很多工具号称能扔一个需求进去自动把整个项目写完。但对于 API 服务这类需要精确掌控的项目我建议第一轮先不要上全自动 Agent。因为 Agent 在长链路执行中很容易出现自作主张的情况——它会自行添加很多你没要求的依赖包、会自动生成代码——出了问题排查时你根本不知道哪些代码是必要的。手动和 AI 对话、一段代码一段代码地确认虽然慢一点但每一行代码是什么来的你心里有数。3. 真正把 AI 用明白的关键把需求拆成它能听懂的结构我在这个项目里最有价值的体会是**AI 写代码行不行很大程度上取决于你拆需求行不行。**你给它一句写个摘要服务它就只能还你一个玩具你给它一份结构化的业务规格它才会还你一份可以上线的代码。3.1 从一句话到结构化的业务规格我动手前给自己写了一份需求拆解稿内容大概是这样技术栈Python 3.11 FastAPI uvicorn requests 库核心流程接收 POST 请求 - 校验字段 - 调用大模型 API - 解析响应 - 返回 JSON边界条件文本为空时返回 400文本超过大模型上下文限制时返回 413上游超时时返回 502配置项大模型 API Key、请求 URL、模型名全部通过环境变量注入不要硬编码输出要求每个函数都要有类型注解和 docstring错误处理要返回标准 JSON不要抛裸异常这份规格我花了一个小时写写完之后让 AI 生成代码只花了几分钟。前后对比非常明显没有结构描述的 promptAI 会给你一个把所有逻辑堆在一个文件里的脚本有了结构描述它会老老实实给你拆成config.py、llm_client.py、main.py几个模块代码质量天差地别。3.2 我实际用过的 Prompt 模板可以直接抄这里贴一下我在项目里实际使用、验证过效果的 Prompt。核心是角色设定任务清单边界条件输出格式四件套你是一名有 5 年经验的后端工程师。请使用 Python 和 FastAPI 实现一个文档摘要 API 服务。需求如下 1. 提供一个 POST /summarize 接口请求体 JSON 包含 text必填和 max_length可选默认 200。 2. 提供一个 GET /health 接口返回 {status: ok}。 3. 在 llm_client.py 中封装对大模型 API 的调用具体请求地址、模型名、API Key 都从环境变量读取。 4. 错误处理要求text 为空时返回 400调用大模型超时返回 502其他异常返回 500。错误响应统一格式为 {error: 错误信息}。 5. 在 main.py 中创建 FastAPI 实例并配置 CORS 允许所有来源。约束 - 使用 Python 3.11 语法所有函数要有类型注解。 - 不要使用额外框架只在 requirements.txt 中写 fastapi, uvicorn, requests, python-dotenv。 - 生成完毕后列出项目的文件树以及每个文件的职责。这个 Prompt 的关键不是最后一段而是中间那一大段错误处理要求和约束。我试过很多次一旦你省略边界条件AI 生成的代码通常只有正常路径没有异常路径而上线之后真正让你出问题的恰恰是异常路径。3.3 迭代式生成第一版要骨架第二版再加肌肉很多人和 AI 协作的误区是希望一次性拿到完美代码。我的做法是分三轮迭代第一轮只要求能跑通正常路径。拿到代码后在本地启动用 curl 传一段文本成功返回摘要即可这时候不关心错误处理是否完备。第二轮把上面 Prompt 里的错误处理和配置项要求扔给它让它重构代码。AI 在在已有代码上做修改的表现远远好于从零生成一个完整系统所以第一轮生成的代码就是给第二轮做跳板的。第三轮自己审查代码把不合理的地方挑出来逐条让 AI 修复。这个流程走完代码达到上线的稳定程度。4. 从零生成 API 服务的实操记录AI 只回答决策我来下这一节用流水账的方式记录我实际把项目跑通的全过程重点放在AI 的输出当时长什么样以及我做了哪些决策上。4.1 新建项目与依赖安装我先创建了一个干净的虚拟环境。这一步没有让 AI 做——不是因为它做不到而是因为依赖安装涉及本机 Python 版本、系统路径AI 给的命令不一定适配你的机器手动执行更稳妥。mkdir doc-summary-api cd doc-summary-api python3 -m venv venv source venv/bin/activate pip install fastapi uvicorn requests python-dotenv安装完成后我照着 3.2 的 Prompt 把需求发给 AI拿到了一张项目文件树。AI 给的初始版本结构是这样的doc-summary-api/ main.py # FastAPI 入口 llm_client.py # 封装大模型调用 config.py # 读取环境变量 requirements.txt .env.example # 环境变量模板有个细节值得提AI 自己生成了.env.example这个文件这是很专业的行为说明它在生成 Code 时已经考虑了不能让 API Key 硬编码进代码库。如果 AI 给你的输出里没有.env.example你应该主动让它补上。4.2 主程序与模型客户端的核心代码AI 第一轮生成的main.py核心逻辑大致长这样。我把它贴在这里不是为了展示代码本身而是为了说明AI 生成什么程度的代码是可以接受的。# main.py 核心片段AI 第一轮生成我做了少量调整 from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field import requests from config import settings app FastAPI(titleDoc Summary API, version0.1.0) class SummarizeRequest(BaseModel): text: str Field(..., min_length1, description需要摘要的原文) max_length: int Field(200, gt0, le2000) class SummarizeResponse(BaseModel): summary: str app.get(/health) def health(): return {status: ok} app.post(/summarize, response_modelSummarizeResponse) def summarize(req: SummarizeRequest): try: result call_llm(req.text, req.max_length) except TimeoutError: raise HTTPException(status_code502, detail上游模型请求超时) return SummarizeResponse(summaryresult)AI 生成的这一段已经能跑通了但离线上可用还差得远。比如它的call_llm函数最初直接把 API Key 写成sk-xxxx的占位符我第二轮 prompt 里明确要求从环境变量读取它才改成os.getenv()。这就是为什么不能把 AI 的产出直接当成品的原因它在规则理解上能做到但在自觉遵守安全规范上还差不少密钥管理这类安全红线必须自己盯死。4.3 本地联调curl、/docs 和真实调用代码生成后验证成本很低。我在虚拟环境里执行uvicorn main:app --reload --port 8000打开http://127.0.0.1:8000/docs页面上已经出现两个接口的可视化调试面板。我点开/summarize在请求体里粘贴了一篇几百字的技术说明点击 Execute很快就看到了摘要结果。这里有一个让我印象很深的点AI 生成的代码里调用大模型的max_tokens参数取值是max_length * 2。它是这么解释的一个汉字大约对应 1 到 2 个 token所以把max_length放大两倍后传给max_tokens摘要更容易得到接近 max_length 上限的结果。这是一个典型的AI 工程心得但如果我不问它也不会主动解释。所以我建议**拿到 AI 生成的代码后凡是看到有魔法数字比如*2、10、len(text) // 4都追问一句这个数值怎么来的。**问出来的解释往往能让你发现一些算法细节甚至发现 bug非常划算。4.4 调用大模型时最容易踩的认证坑我在让服务真正对接大模型 API 时遇到了一个非常典型的错误报错信息大概是llm-deepseek: no api key for provider route deepseek-official这个报错说的是在某个 provider 路线上没有找到 API Key。这不是我们代码里的问题而是调用链路上层框架当时我还在评估一个开源编排工具自己维护的 key 配置为空。遇到这类报错第一反应应该是去检查你使用的 SDK 或框架的密钥配置文件而不是检查自己的请求代码。我最后的处理方式是放弃中间编排框架直接用最朴素的requests库调大模型。对于这种几行代码就能完成的功能引入一个中间框架反而是负担。这个决定也是 AI 替我分析的——我把我看到报错的全过程发给它它列了一个排查清单其中第三条写着评估是否真的需要这层框架我一对照确实不需要。有时候 AI 辅助编程的价值不是帮你写代码而是帮你在岔路口做决策。5. 调试链路实录把报错信息喂给 AI 的正确姿势这一节我想专门写调试因为这是 AI 辅助编程里信息密度最高、最像老手带新手的环节。很多人用 AI 排错没效果问题往往出在报错信息喂得太粗糙。5.1 上下文超限错误观察 1048576 这个数字的启示有一次我拿一篇很长的论文做测试接口直接崩了抛出的报错是api error: 400 this models maximum context length is 1048576 tokens. however, your messages resulted in 1050032 tokens这个报错里的1048576是模型的最大上下文长度1050032是我们这次请求实际占用的 token 数。问题一目了然文本太长超了模型上限。我把完整报错发给 AI问它这种情况接口应该怎么处理它给出两个方案并排了优先级第一是在接口层前置校验算一下文本和摘要的 token 预估超了就返回 413 状态码让调用方自己决定要不要分段第二是后端自动做截断。它的理由是**摘要任务里你强行截断长文本可能会导致核心信息丢失语义完整性被破坏所以应该把如何处理长文本的决策权交给调用方而不是后端默默处理。**我完全同意最终在llm_client.py中加了 token 长度估算逻辑超限时提前返回 413。这个案例也是我理解的超参数友好——1048576很大普通项目几乎不会触发但只要你做了接收用户输入并转发大模型这类服务它早晚会遇到。提前设好防御逻辑比上线后被用户用一段长文本打挂强太多。5.2 模型返回响应格式错误messages.content.type 的类型陷阱另一个报错同样有代表性出现在我尝试传 multiple content parts 的时候。当时报错是api error: 400 the parameter messages.content.type specified in the request这个报错的核心是messages.content的格式不符合上游 API 的要求。在我调的大模型服务里content字段既可以是简单字符串也可以是 content part 数组数组里每个 part 要有type字段比如typetext或typeimage_url。我传给它的请求里content 数组少写了 type 字段导致上游直接拒绝。排查方案很朴素我拿到报错后直接把完整请求参数脱敏后和文档链接一起发给 AI让它比对 Oj 规范。它指出问题后我在代码里加了格式校验——如果将来要支持多模态输入就走数组格式否则统一走字符串格式。这类上一秒查文档、下一秒改代码的操作AI 的效率是人肉翻文档的十倍。5.3 AI 幻觉出来的伪 API怎么识别并纠正调试过程中还有一类坑跟报错无关是 AI 自己编出了根本不存在的 API。有一次我让它在llm_client.py里添加指数退避重试逻辑它直接写了一段依赖某个函数的重试代码但那个函数在requests库里根本不存在。代码能运行——因为它 import 的时候没有语法报错只有运行到那一步才会炸。怎么防这种坑我的经验就一条**AI 生成的代码第一次运行报错后先看报错再用它排查别急着让它现场改。**让 AI 自己指出你刚才写的方法不存在请重新生成它的准确率会高很多。这听起来像玄学但确实有效。5.4 环境变量与密钥管理Permission Denied 的另一层含义调试到 Docker 部署阶段我遇到过一次permission denied while trying to connect to the docker api。这个报错的本质是当前用户没有权限访问 Docker 的 socket。我当时第一反应是是不是 API Key 权限不够被 AI 纠正了——它提醒我这个报错和你大模型 API Key 一点关系都没有是你本机的 Docker 权限问题。解决方法要么把用户加入 docker 组要么用sudo。**这让我意识到一个很普适的经验报错信息带 docker 和 api 两个词时先分清是 Docker API 还是你的业务 API别把系统层面的权限问题当成应用层问题。**排查路径错了折腾几小时都是浪费。6. 上线前必须补的工程化细节密钥、CORS、限流与日志本地能跑通最多算完成 50%。API 服务真正难的是让别人也能安全地用。6.1 环境变量管理AI 最容易违反的安全红线整个开发过程中我反复对 AI 强调一句话API Key 不许出现在代码里。即便如此它在第一轮生成时还是给了硬编码占位符我第二轮要求改掉之后它又在一个测试文件里把 Key 直接写了出来。这让我非常警惕。最终我用了一套安全配置模板# .env.example LLM_API_KEYsk-xxx LLM_API_URLhttps://api.example.com/v1 LLM_MODEL_NAMEmodel-name项目启动时读取顺序是先用python-dotenv加载.env再让代码从环境变量读取保证不管在本地还是容器里都能拿到配置。需要强调**.env文件永远不要提交进 Git 仓库并且在.gitignore里写明.env。**这是用 AI 开发时最容易被忽略的安全问题因为 AI 只关心功能不关心你的密钥是不是泄露到了 GitHub。6.2 CORS、超时与重试三个不能少的配置FastAPI 里配 CORS 只需要几行代码但很多人会忘。我这次做的 API 是要给一个前端页面调用的如果不配 CORS浏览器里会被同源策略拦下来。AI 生成的初始代码里 CORS 配置是一个很宽松的allow_origins[*]我上线前改成白名单形式这也是 AI 提醒我线上环境不建议通配符之后改的。超时与重试配置在llm_client.py内部。我让 AI 实现的逻辑是单次请求给 30 秒超时连接失败后重试 2 次使用 1 秒、2 秒的递增退避如果重试后仍然失败抛一个 IOException。这套逻辑简单但并不简陋它保证了一个原则**你把上游大模型当外部依赖对待而不是当本机函数对待。**多数人第一次写 AI 调用代码时不会考虑上游可能 100 秒不响应但真实情况是大模型 API 受负载影响延迟波动非常大。6.3 调用量与日志观测把 API 服务当孩子养项目上线后我看的最多的不是功能代码而是日志。我在 FastAPI 里加了一个简单的中间件打印每个请求的耗时、状态码、来源 IP。大模型 API 的调用量、延迟、失败率我也通过后台日志聚合出来。这一步的价值在实际运行一周后体现得很明显日志显示max_length参数经常被前端传成undefined而 AI 生成的pydantic模型用默认值挡掉了这个坑延时统计显示大部分请求在 2 秒内但有 3 次请求耗时超过 20 秒全部发生在同一时间段我判断是上游服务高峰期的限流不是本地问题。如果没有日志这些问题只能靠用户反馈才知道那被动多了。到这里整个项目从一句标题变成了一个可以线上调用的 API。回头看整个开发过程AI 的贡献大概占 60%剩下 40% 的价值是人类做的——拆需求、拍板、检查安全红线、做决策。其实做这一期最大的收获不是 API 本身而是我找到了一个和 AI 协作的安全节奏先自己把规格拆干净再让 AI 填肉最后每一行代码都要过自己的眼睛。我个人的体会是未来工程开发的门槛会越来越低但决策能力的门槛会越来越高。AI 可以帮你写出接口但要不要对外暴露这个接口、参数语义怎么定、失败了怎么返回、密钥怎么保护——这些事 AI 不会替你把关。把这个节奏练熟比会抄代码重要得多。下一篇小项目实战我计划在这个同一个 API 服务里加入多模型自动路由让服务根据成本、延迟、效果动态选择底层模型到时候想顺手聊聊怎么用 AI 做技术选型的风险控制。

AI辅助从零搭建文档摘要API：FastAPI与大模型调用实战

相关推荐

DBpedia TTL 导入 Neo4j：Scala 转换与批量导入避坑指南

老旧产线零停机加装机器视觉：非侵入式技改与嵌入式Linux实战

多机共用 WorkBuddy 账号：跨机双写同步与缓存分离实战指南

更多资讯

T3技术栈实战：用tRPC+Prisma打造代码片段管理工具

MATLAB 2021a 实现小球弹射强化学习控制

SpringBoot蛋糕店系统：入门级可交付业务闭环实践

SpringBoot 三层架构里 DTO 该放哪一层：从鸿蒙登录接口返回密码说起

SpringBoot2.7+MyBatis-Plus+MySQL5.7校园小程序实战

W5500 DHCP实战：状态机控制、realnde PHY协同与保底机制

今日更新

Agent-Reach：打通大模型触达外部系统的最后一公里

深度学习图像隐写分析实战：从CNN原理到毕设源码全解析

AI赋能知识产权供需匹配：专利评估、需求挖掘与多路召回工程实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？