我第一次把 AI 应用部署到服务器时踩下四个大坑

坑1️⃣ : 本地能跑。却在服务器全炸掉 — 环境不一致

🔍 翻车现场

bash

python app.py # ✅ 正常启动

pip install -r requirements.txt # ❌ 编译 chromadb 报错：“C++ 编译器版本不对” python app.py # ❌ ModuleNotFoundError: No module named '_sqlite3'

Python 的依赖管理是一门玄学 —— 不同 OS、不同 Python 版本、不同程序库，都可能让一样的代码无法运行。是 chromadblangchain 等需要 C/C++ 的大型第三方库。一旦编译失败，就会彻底卡住。

✅ 正确做法：Docker 打包，让“一份代码 = 一份可复现环境”

Dockerfile 示例

dockerfile FROM python:-slim

RUN apt-get update && apt-get install -y \ build-essential \ && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000 CMD

docker‑compose 示例

yaml version: '3' services: 再看app。build: . 说到ports，- "8000:8000" envfile: - .env # 不放进 Git 的秘密文件夹，可通过 CI 自动注入变量 environment: OPENAIAPIKEY:${OPENAIAPIKEY} DASHSCOPEAPIKEY:${DASHSCOPEAPIKEY} dependson: - chromadb

chromadb: image这方面，chromadb/chroma:latest # 官方官方镜像已包含所有必要建立工具与 C/C++ 库。至于ports，- "8812:8812" volumes: - chroma_data:/chroma # 持久化存储向量索引

volumes: chroma_data:

主要要点的观点是，

Java 开发者可类比为 “WAR 包 + Tomcat + JDK 全部打包进镜像”，保证任何机器都能正常启动，无需关心宿主机上的 JDK 与 JRE 区别。说起来，

坑2️⃣ : 并发太高导致 API 挂掉 — 同步调用 LLM

FastAPI RAG 服务示例：

python from fastapi import FastAPI。HTTPException

app = FastAPI

@app.get def chat: result = rag.query # 同步调用 LLM，大约耗时5秒!return {"answer": result}

压测结果的观点是。

text 10 个并发 -> 平均响应时间 ~3.2s ✔️ 50 个并发 -> 平均响应时间 ~15s ⚠️ 200 个并发 -> 超时占比超过30% ❌

再看原因，

1. LLM 调用是慢 IO，同步等待会占满线程池。
2. 有数百个线程等待 → CPU 与内存爆炸。
3. 大多数 LLM 接口都有速率限制，高并发直接返回 429 Too Many Requests。

✅ 正确做法：异步 + 队列 + 限流三防护链

异步调用示例

python import asyncio,uuid,json,redis,os,jsonpickle as jsonpicklelib from fastapi import FastAPI,HTTPException from pydantic import BaseModel from langchainopenai import ChatOpenAI

app = FastAPI redis_client = redis.Redis

MAXLLMCONCURRENT = int) # 控制最大并发数 llm_semaphore = asyncio.Semaphore

async def asyncllmcall -> str : llm = ChatOpenAI return ).content

async def ratelimitedllmcall -> str : async with llmsemaphore : return await asyncllmcall

class ChatRequest: question:str

@app.post async def chat: answer = await ratelimitedllm_call return {"answer": answer}

@app.post async def submitreport: taskid=str) redisclient.lpush("reportqueue"。json.dumps) return {"taskid": taskid,"status":"processing"}

@app.get async def getreport: data=json.loads) return {"taskid": task_id,"status":"done","progress":data}

至于三层防御说明，

1. *异步调用 * – 请求完成后立即释放事件循环，可继续处理新请求。
2. *信号量限流 * – 最大允许10个并行 LLM 调用，避免爆炸性资源占满。
3. *任务队列 * – 对长任务如报告生成放入后台处理，不阻塞前端接口。说起来，

坑3️⃣ : API Key 写死导致泄漏风险

python

OPENAIAPIKEY ="sk-xxxxxxxxxxxx" DASHSCOPEAPIKEY ="sk-yyyyyyyyyyyy"

llm = ChatOpenAI

推送至 GitHub 后仅两小时就收到邮件：“你的 API Key 已被消费 $X”。

✅ 正确做法：环境变量 + .env 文件 + CI/CD 注入

main.py 示例

python import os # 从操作程序读取变量 from dotenv import loaddotenv loaddotenv

llm = ChatOpenAI( apikey=os.getenv,modelname='qwen-plus' )

.env 文件

OPENAI_API_KEY=sk-xxxxxxxxxxxx DASHSCOPE_API_KEY=sk-yyyyyyyyyyyy MAX_LLM_CONCURRENT=10

gitignore 中排除敏感文件：

.env* .env.example*

CI/CD 自动注入策略：

• 在 Kubernetes 中使用 Secrets 或 Vault 注入容器环境变量。
• 在 GitHub Actions 中使用 secrets 存储键值，并通过 secrets. 注入工作流。

坑4️⃣ : 没有监控与告警导致质量下滑被使用者发现

RAG 上线两周，一切看似正常。但某日使用者投诉：“回答越来越离谱。”日志显示向量索引损坏，只返回低质量回答，而应用没有报错信息。

✅ 正确做法：三层监控程序

1. 结构化日志 – 每次查询记录 question、answer 长度、耗时等信息，以 JSON 格式便于搜索和分析。老实说，
2. 健康检查 Endpoint /health – 检查 LLM 响应时间、向量检索可行性还有 Redis 状态。并返回整体健康状态，说起来，
3. 指标收集 /metrics Endpoint – 提供 Promeus 可抓取的数据。如查询延迟、错误率、答复长度等。

示例实现片段

python import logging,json,time from datetime import datetime from fastapi import FastAPI logger=logging.getLogger logger.setLevel formatter=logging.Formatter( '{"time":"%s","level":"%s","event":"%s"}' ) handler=logging.StreamHandler handler.setFormatter logger.addHandler

class AILogger : @staticmethod def log_query: logger.info} | latency={latency:.2f}s')

@app.get async def healthcheck: checks={} try : start=time.time await ratelimitedllmcall checks= {"status":"ok","latency":time.time-start} except Exception as e : checks= {"status":"error","detail":str} try : docs= checks= {"status":"ok","doccount":len} except Exception as e : checks= {"status":"error","detail":str} status='ok' if all) else 'degraded' return { 'status': status,'checks':checks }

@app.get async def getmetrics: return { 'querylatency': metrics.getstats,'errorcount': metrics.get_stats }

从告警阈值建议来看，

Java 开发者可以把上述方案视作 Spring Boot Actuator 的完整实现— /actuator/health。/actuator/metrics,日志采用 Logback Structured Logging.

📦 完整项目结构示例

text ai-rag-app/ ├── app/ │   ├── __init__.py │   ├── main.py # FastAPI entry point │   ├── rag.py # RAG core logic │   ├── config.py # Config read from env │   ├── logger.py # Structured logger │   └── metrics.py # Metrics collector ├── tests/ │   ├── test_unit.py │   ├── test_integration.py │   └── golden_dataset.json ├── Dockerfile ├── docker-compose.yml ├── requirements.txt ├── .env.example # 环境变量模板 ├── .env # 真正运行时 secret └── .gitignore

至于部署命令，

bash docker compose up --build -d docker compose logs --follow app curl http://localhost:8000/health curl http://localhost:8000/metrics

🎯 四个坑 & Checklist