最近我朋友问我你说现在AI写代码这么厉害那我想自己做个接口给小程序用是不是都不用找后端了我当时的回答是理论上确实可以但现实里有不少坑要踩。他这句话也勾起了我的兴趣于是真就花了一个周末用AI从零开始把一个API服务搭了起来从注册大模型平台、设计接口路由、写核心逻辑到部署上线全部走了一遍。这篇文章就是这次实战的完整记录希望能给正在考虑AI辅助开发的朋友一些可参考的思路。在这个小项目里我用的是Python生态里很成熟的FastAPI框架加上大模型平台提供的API来提供业务能力。项目本身不复杂但完整覆盖了API服务的生命周期环境准备、需求设计、编码实现、本地测试、容器化部署。如果你是一个刚入门后端开发的新人或者是在做大模型应用但一直停留在本地脚本调用阶段的老手这篇文章应该能帮你把散落的知识点串起来。1. 项目概述与整体思路拆解1.1 为什么选择AI辅助开发API这个切入点先说结论AI真正能提效的地方不是让它替你想清楚所有事而是让它帮你把已经想清楚的逻辑快速变成代码尤其是在CRUD、接口封装、参数校验这种模式化很强的部分。我做这个项目的出发点很简单工作任务里经常需要给前端提供接口但传统开发模式下开发一个接口往往要做大量重复性工作——写路由、定义请求模型、做参数校验、写接口文档、处理异常。这些工作占用时间不少但技术含量并不算高。AI编程工具和AI大模型API的出现恰好把这块效率短板补上了。用AI大模型的API我们可以把自然语言输入转换成结构化输出这类能力直接封装成接口用AI辅助写代码可以让它帮你生成FastAPI的模板代码、pydantic模型定义、数据库连接代码等然后你只需要review和调整。这两个AI虽然都叫AI但解决的是不同层面的问题。前者是业务能力后者是生产效率。我这次的项目把两者都融合进来了属于一个很典型的AI驱动的全栈小项目。1.2 技术选型的核心考量技术选型这块我直接说结论然后解释为什么技术点选择方案备选方案选择理由语言PythonNode.js、Go生态最成熟AI辅助生成的代码准确率最高API框架FastAPIFlask、Django自带OpenAPI文档、异步支持好、参数校验靠类型注解搞定大模型APIDeepSeek APIOpenAI、智谱、讯飞星火国内直连、价格友好、兼容OpenAI格式部署方式Docker Nginx纯systemd环境隔离后续迁移方便密钥管理环境变量配置文件防止密钥泄露进git仓库有些朋友可能会问为什么不用FlaskFlask当然可以但FastAPI天然适合做大模型能力封装——因为大模型请求通常是IO密集型而FastAPI对异步支持的力度远强于Flask。另外FastAPI基于Python类型注解自动生成OpenAPI文档这意味着前端同学调接口的时候可以直接打开/docs页面看参数说明连单独维护接口文档的功夫都省了。大模型API选DeepSeek理由比较现实它兼容OpenAI的接口格式拿OpenAI的SDK或者直接requests调用都能通而且在国内访问稳定。后来我也顺手对比了智谱的GLM系列和讯飞星火基本逻辑都差不多只是请求地址和鉴权方式略有不同。1.3 项目需求场景设定做项目之前先明确要做什么。我没有去搞一个脱离实际需求的demo而是选了一个我实际会用到的场景做一个文章摘要API。需求是这样的用户往你的API提交一段正文API调用大模型生成摘要再把摘要返回给用户。这个场景看起来简单但在设计层面其实能拆出几个关键点需要设计POST接口接收长文本要对文本长度做校验防止有人恶意提交超大文本要调用大模型API处理好超时、错误重试需要给每次请求设置一个合理的超时时间避免后端被慢请求拖死需要一个简单的鉴权机制不能谁拿到接口地址就能白嫖。这个需求设定能让整篇文章的每个环节都有实际落点而不是三五行的hello world。后面的所有拆解和实操都是围绕它展开的。2. 核心细节解析与实操要点2.1 大模型API接入的细节从申请到第一次调用API服务的引擎是大模型所以第一步要先搞定能稳定调用的大模型API。我在这里踩过一个坑也发现一个很多人忽略的细节国内大模型平台的API文档更新非常快网上教程里的参数可能已经过时了最靠谱的方式是直接看对应平台的最新文档。以DeepSeek为例申请流程很简单打开官网注册账号进入开放平台创建一个API Key充值少量金额新用户通常有赠送额度查看文档确认接口地址和模型名称。这里要特别提醒API Key本质上就是你的钱包。谁拿到你的Key谁就能用它调用模型产生费用。所以绝对不要把它写死在代码文件里更不要提交到GitHub。正确的做法是放到环境变量或.env文件里并且在.gitignore中把.env排除掉。第一次调用大模型API可以不用急着写代码。先拿curl试一下确认连通性和鉴权没问题再说。拿DeepSeek举例请求的基本格式是curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d { model: deepseek-chat, messages: [ {role: system, content: 你是一个专业的文章摘要助手。}, {role: user, content: 请为下面的文章生成200字以内的摘要...} ] }第一次调用成功之后你会对大模型API有一个直观的感受它本质上就是一个你给文本它回文本的远程函数。如果这个curl测试都不通那就别急着往下写先把鉴权、网络代理、接口地址这三个环节排查清楚。2.2 请求参数设计temperature、max_tokens与超时控制很多人在接入大模型API时只关心传prompt却忽略了几个直接影响服务稳定性的参数。temperature控制输出的随机性。做摘要这种任务取值在0.2到0.5之间比较合适。取值太高模型可能发挥得过猛摘要里出现原文没有的内容取值太低虽然稳定但可能偏死板。我之前踩过一次坑把temperature设成了1.0结果同一个文章每次调用生成的摘要都不一样连关键结论都能变。所以摘要类任务我建议固定在0.3。max_tokens限制模型返回答的最大长度。如果不设模型可能会生成长篇大论一方面浪费token另一方面也拖慢响应时间。做摘要200到500个token基本够用。timeout很多SDK默认的超时时间很长比如OpenAI的Python SDK可能默认等很久。但API服务讲究响应速度客户端等不起。我建议在调用时显式设置timeout比如timeout30意思是30秒没有响应就主动断开避免请求堆积。这里顺便说一句热词里有人遇到了maximum context length is 1048576 tokens这种报错意思是输入加上输出超出了模型的上下文窗口上限。虽然1M的上下文已经很大了但如果你往API里塞了一个几十万字的长文本照样会爆。所以API服务里一定要做输入长度限制不能把大模型API直接暴露给任何人无限制提交。2.3 API服务自身的架构路由、校验与限流我们的API服务本身要承担的职责除了转发请求到大模型还包括一堆安全防御工作入参校验用FastAPI的pydantic模型定义请求体。比如限制text字段的长度不超过5000字类型必须是字符串。这能挡住大多数恶意请求。鉴权设计既然是自己用或者小范围用可以做一个简单的Bearer Token鉴权。用户在调用接口时必须在Header里带上Authorization: Bearer 你的密钥服务端校验通过才放行。限流防止某个用户疯狂调用把你的API额度耗尽。FastAPI生态里有现成的中间件可以用比如slowapi。稍微简单一点的做法是先用内存做一个计数器同一个IP一分钟最多调用N次超过了就返回429状态码。这些设计不是过度设计而是API服务能长期稳定运行的基本保障。我在实际项目中见过太多能跑就行的服务上线之后被人刷了几百次请求费用直接爆表回头再补救就晚了。3. 实操过程与核心环节实现3.1 项目初始化与FastAPI骨架搭建先说环境准备。我用的是Python 3.11实测下来3.10以上都没问题。创建一个新目录初始化虚拟环境mkdir article-summary-api cd article-summary-api python -m venv venv source venv/bin/activate # Windows上用 venv\Scripts\activate pip install fastapi uvicorn pydantic openai python-dotenv这里的openai是官方Python SDK为什么装它因为DeepSeek、智谱这类国内大模型平台都提供了兼容OpenAI接口格式的端点所以直接用OpenAI SDK改base_url就能完成对大模型API的调用。不用每个平台都去适配一套完全不同的SDK省心很多。这种方式也被越来越多的国内大模型厂商采纳基本已经成了事实标准。然后创建项目文件结构article-summary-api/ ├── main.py # FastAPI入口路由定义 ├── llm_client.py # 大模型调用封装 ├── schemas.py # pydantic请求/响应模型 ├── auth.py # 简单鉴权依赖 ├── .env # 环境变量不入库 ├── .env.example # 环境变量示例入库 ├── requirements.txt # 依赖清单 └── Dockerfile # 后续部署用main.py的第一版代码非常简单from fastapi import FastAPI from schemas import SummaryRequest, SummaryResponse app FastAPI( titleArticle Summary API, description调用大模型生成文章摘要的API服务, version1.0.0, ) app.post(/api/v1/summarize, response_modelSummaryResponse) async def summarize(req: SummaryRequest): # 核心逻辑暂时先写一个占位实现 return SummaryResponse(summaryf收到文本长度{len(req.text)}字)这样写完之后启动服务uvicorn main:app --host 0.0.0.0 --port 8000 --reload浏览器打开http://localhost:8000/docs你就能看到一个交互式的API文档页面可以直接在页面上测试POST接口。到这一步一个标准的API服务骨架就已经跑通了。很多教程到这里就结束了但我们还得继续往里填真正的逻辑。3.2 大模型调用封装与核心接口实现接下来把大模型能力接进来。为了避免main.py里堆太多代码我单独做了一个llm_client.py来封装调用逻辑。# llm_client.py import os from openai import OpenAI client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL, https://api.deepseek.com), ) SYSTEM_PROMPT ( 你是一名专业的中文文章摘要助手。 请阅读用户提供的文章生成一段简洁、准确的摘要。 要求摘要不超过200字保留文章的核心观点和数据使用中文输出。 ) def generate_summary(text: str, max_tokens: int 300, timeout: int 30) - str: try: resp client.chat.completions.create( modelos.getenv(LLM_MODEL, deepseek-chat), messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: text}, ], temperature0.3, max_tokensmax_tokens, timeouttimeout, ) return resp.choices[0].message.content.strip() except Exception as e: raise RuntimeError(f大模型调用失败: {str(e)})注意几点base_url必须设置为大模型平台提供的兼容端点。比如DeepSeek就是https://api.deepseek.com在它的文档里能找到准确地址不要自己瞎拼调用的大模型名称以平台最新文档为准。有些平台会区分deepseek-chat和deepseek-reasoner前者适合通用对话后者带推理能力但速度更慢。摘要场景用deepseek-chat就好异常一定要统一抛出来让上层接口层去统一处理不能让大模型的异常细节直接暴露给客户端。然后把schemas.py定义好# schemas.py from pydantic import BaseModel, Field, field_validator class SummaryRequest(BaseModel): text: str Field(..., description需要摘要的文章正文) field_validator(text) classmethod def validate_text_length(cls, v): if len(v) 50: raise ValueError(文章太短不足以生成摘要) if len(v) 5000: raise ValueError(文章过长最大支持5000字) return v class SummaryResponse(BaseModel): summary: str character_count: int这里我用pydantic的内置校验能力直接在请求进入路由之前就把非法输入拦截掉。如果用户传的文本太长FastAPI会自动返回422 Unprocessable Entity根本不会往下走。这样一来即使哪天有人故意往接口里塞超长文本也只是被校验逻辑挡掉根本消耗不了大模型的token。3.3 鉴权中间件的实现鉴权这块我一开始想用FastAPI自带的依赖注入机制后来发现其实做一个简单的依赖函数就非常干净# auth.py from fastapi import Header, HTTPException API_TOKEN os.getenv(API_TOKEN, dev-token) def verify_token(authorization: str Header(default)): if authorization ! fBearer {API_TOKEN}: raise HTTPException(status_code401, detail无效的访问令牌)然后在main.py的路由里加上这个依赖app.post(/api/v1/summarize, response_modelSummaryResponse) async def summarize(req: SummaryRequest, _Depends(verify_token)): try: summary generate_summary(req.text) return SummaryResponse( summarysummary, character_countlen(req.text), ) except RuntimeError as e: raise HTTPException(status_code502, detailstr(e))这样一个写了token的请求就能被401拦下来产生不了任何费用。虽然这个鉴权比较基础但对于个人小项目、内部服务来说已经完全够用了。真要开放对公网建议再接上更成熟的网关方案但在那之前别让裸奔的服务挂在公网上。3.4 部署Docker容器化与常见坑部署到大模型API服务的时候还是绕不开Docker。为什么用Docker因为我不想在服务器上配一堆Python环境依赖直接用容器打包所有东西哪里都能跑。Dockerfile我写得很简单FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . ENV PYTHONUNBUFFERED1 EXPOSE 8000 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]构建并运行docker build -t article-summary-api . docker run -d --name summary-api \ -p 8000:8000 \ --env-file .env \ article-summary-api这里我踩过一个大坑启动容器后接口一直报Permission denied while trying to connect to the Docker api后来排查发现是构建镜像的过程中pip尝试连接外部源时没有网络权限最终定位到是公司内网环境的代理设置问题。如果你在自己服务器上也遇到类似的权限类报错优先检查构建镜像时的网络层面是否拉取了基础镜像、依赖源是否可达以及宿主机上是不是有旧容器占用了端口。还有一个小细节如果你要通过Nginx反代访问API服务在Nginx配置里要把请求头Authorization代理给后端不然前端带过来的token根本传不到API服务里表现就是所有请求都401。4. 常见问题与排查技巧实录4.1 API Key相关的坑Key写死进代码这个我看过太多次了越大的项目越容易出这种事。一旦代码或者镜像推送到公共仓库你的Key就相当于丢了。正确做法是用环境变量部署时通过--env-file或者云平台的密钥管理来注入。Key轮换之后服务没重启有时候你在平台重新生成了Key但服务进程还在用旧Key表现就是所有请求突然401或者403。排查的时候除了看服务端日志也要确认进程是不是加载了新环境变量。用Docker部署的话改了.env要重新docker run不是改个文件就生效的。4.2 大模型API调用失败的排查清单这里我把实际遇到过的问题整理成了一张速查表现象可能原因排查方式请求返回401/403API Key失效或错误检查环境变量去平台确认Key状态返回400 model not found模型名写错了对照平台文档确认当前正确的模型名返回400 context length exceeded输入文本太长或max_tokens太大查看具体报错提示的数字减小输入或降低max_tokens请求超时网络不稳定或模型推理时间过长设置合理timeout对超时请求做重试或降级返回内容截断max_tokens设置偏小增大max_tokens或让程序检测finish_reason账单异常飙升API Key泄露或被刷立即吊销Key加鉴权和限流说一个很有价值的细节大模型平台的报错信息里经常会包含非常具体的上下文窗口占用数字比如this models maximum context length is 1048576 tokens... you requested N tokens。遇到这种情况最好的办法不是盲目调参而是读一读报错里的数字确认到底是输入太大还是max_tokens设置不合理。我之前就遇到过因为max_tokens设成4096导致输入中等长度的文章也报超限的乌龙。4.3 FastAPI服务本身的常见问题CORS跨域报错如果你的前端页面跑在另一个域名下比如http://localhost:5173而后端跑在http://localhost:8000浏览器会拦截跨域请求。解决办法是添加CORS中间件只允许你的前端域名访问from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[http://localhost:5173], allow_methods[POST], allow_headers[*], )注意allow_origins别随手设成[*]那等于彻底开放了跨域访问权限。如果你觉得反正有鉴权结果鉴权被绕过的场景在CSRF里很常见这里不多说安全原则就是最小授权。端口被占用uvicorn启动时报Address already in use这个通常就是之前有个没停干净的服务进程还在跑。排查命令lsof -i :8000找到对应的PID确认没用了再kill掉。用Docker的话docker ps看一眼还有没有旧容器在占用端口docker rm -f清理掉就行。服务重启后环境变量丢失这个问题在通过systemd管理服务的人里特别常见。如果你用systemd启动API服务记得在[Service]段里加上EnvironmentFile或Environment配置不然服务起来之后读不到.env里的Key所有请求都会报鉴权或调用大模型失败。4.4 预算与限流的现实问题最后分享一个很多人没意识到的问题大模型API是按token计费的一个没限流的API服务放在公网上就像把钱包挂在路边。哪怕只是被爬虫扫到也可能因为自动探测请求产生大量费用。我建议的最低限度配置是必须有一个API Key鉴权拒绝无token请求对每个用户或IP做基础限流比如每分钟最多10次在代码层面对输入文本长度做硬限制这个我们已经在pydantic中实现了在服务端日志中记录每条请求的用户标识和调用量方便月底看账单时核对。这些功能加起来代码量不大但对整个API服务的长期可用性是决定性的。别小看这些防御性编程小项目一旦上线跑起来再回头加这些可比一开始就写好要麻烦得多。我个人实际操作下来的体会是用AI从零搭建API服务这件事效率提升最明显的环节是写代码和查报错但最花时间的反而是想清楚要做什么和把异常处理做完整。AI能帮你把想法快速变成80分的东西剩下20分的稳定性和安全性需要你自己去补这也是区分能用和好用的分水岭。最后再分享一个小技巧如果你也在用FastAPI接大模型API建议把不同的下游模型API封装在一个统一的LLMClient接口里后续要换厂商只需要改内部实现路由和业务层完全不用动。我这次用的DeepSeek下次想换智谱GLM改动量就是新写一个实现类的事。这个扩展思路其实更适合有多个API要接的场景以后我要是数据过了流量峰值也会考虑加个异步任务队列把同步请求改造成异步回调模式。那又是另一个坑了等有机会再写一篇专门讲。