KNOWLEDGE NOTE / programming

Python AI 项目实战精选

把模型调用、数据处理、网页接口与项目安全整理成可复用的实践流程。

创建
2026年9月24日
更新
2026年10月15日

Python AI 项目实战精选

摘要

将课件中的模型调用、HTTP、数据分析和 Web 开发案例收敛为小型 AI 项目结构。重点放在密钥保护、输入校验、错误处理和可验证结果,不依赖某个特定服务商的旧版示例代码。

正文

1. 最小可维护项目结构

text
my-ai-app/
├── app/
│   ├── main.py
│   ├── llm_client.py
│   └── schemas.py
├── tests/
├── .env.example
└── README.md

将模型调用放在单独模块,便于替换服务商、统一超时和错误处理。环境变量示例文件只能写变量名称,不放真实值;真实密钥放在本地环境变量或密钥管理服务中,并确保不会提交。

python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ["LLM_BASE_URL"],
)

兼容 OpenAI 接口只表示请求格式相似,不代表服务商支持完全相同的模型、参数或响应行为。先查看服务商文档,再测试最小请求。

2. 提示词和对话上下文

高质量提示词要说明任务、背景、输入材料、输出格式和约束。结构化任务可要求模型输出 JSON,再由程序验证字段;“要求 JSON”本身不等于校验。

对话历史需要控制长度和敏感信息。不要把所有历史消息无限追加;应基于任务保留必要上下文,并为用户输入设置长度限制。

3. 网络请求和数据采集

使用 HTTP 客户端时要设置合理超时、检查状态码并处理重试和异常。网页采集前检查网站规则、服务条款和数据授权,遵守 robots.txt、访问频率和隐私要求。不要绕过登录、反爬或付费限制。

解析 HTML 时先定位稳定字段,再校验空值和格式;页面结构变化后应让任务失败并报告,而不是悄悄写入错误数据。课程爬虫代码只是学习示例,真实采集须确认合规授权。

4. 表格数据处理

建议把数据分析拆为读取并记录来源、查看类型和空值、明确清洗规则、分组聚合、检查结果、输出并说明口径。保留原始数据。处理含个人信息或业务机密的数据前,确认是否允许上传到外部模型或云服务。

5. API 与测试

将接口输入定义成清晰的数据结构,对必填字段、长度和类型做验证。模型调用、数据库读取和外部 HTTP 请求都可能失败,应区分认证、超时、限流、输入错误和服务端错误。返回给调用方的消息不应包含密钥、堆栈或服务器内部路径。

最少测试:

  • 有效输入能得到结构正确的响应。
  • 空输入、超长输入和错误类型被拒绝。
  • 缺少密钥时快速失败且不泄漏变量值。
  • 模型超时或限流时返回可理解的错误。
  • 流式输出中断时释放连接并记录安全日志。

6. 外部模型接口的错误边界

模型接口失败时先分类,再决定能否重试。网络超时、连接重置、服务端暂时过载和限流通常可以按服务商策略退避重试;认证失败、请求结构错误、配额耗尽或输入过长,重复原请求通常没有帮助。写入型/计费型 POST 请求也不能默认“重试一定无副作用”,应先确认服务是否支持幂等键(同一请求重复提交不会重复产生副作用的标识)。

一个不绑定具体供应商的处理框架如下。send_request 代表项目中经过审查的客户端调用,不是某个供应商的固定 SDK:

python
def call_model(send_request, payload, *, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            response = send_request(payload, timeout=30)
            response.raise_for_status()
            body = response.json()
            if not isinstance(body, dict):
                raise ValueError("模型接口响应必须是 JSON 对象")
            return body
        except TimeoutError:
            if attempt + 1 == max_attempts:
                raise
            # 真实项目在此使用有上限的退避,并记录脱敏后的错误类型。
    raise RuntimeError("模型调用重试次数已耗尽")

这个框架只展示控制流程:实际 HTTP 库的超时异常类型、状态码处理、Retry-After 读取方式和响应对象接口都可能不同,必须按当前依赖版本核对。生产实现还需设置总超时、重试上限和退避上限,避免多个调用层各自重试造成请求风暴。

日志只记录排障所需的请求 ID、模型标识、耗时、状态码和经过脱敏的错误类别。不要记录 API 密钥、完整个人数据、未经授权的提示词或完整模型响应。

7. 接口问题排查顺序

现象先核对处理方向
401 / 认证失败环境变量是否加载、密钥是否过期、请求头格式重新配置受保护的凭证;不能把真实密钥写入代码或公开笔记
400 / 参数错误模型名、消息结构、字段类型、上下文长度对照服务当前 API 文档检查字段;区分客户端校验错误与服务端错误
429 / 限流或配额响应中的限流信息、并发量、账户配额限制并发、按 Retry-After 等策略退避;额度不足时不要盲目重试
连接超时DNS、代理、网络策略、连接超时与读取超时区分连接未建立和模型处理太慢;只延长有依据的超时
JSON 解析失败响应状态码、内容类型、是否为错误页或流式分片先检查状态码和响应体类型,再解析 JSON;流式响应应使用专门解析器
结果格式错误输出约束、响应字段、模型版本通过程序 schema 校验,校验失败后明确降级或让用户重试

8. 项目从原型到可维护服务的检查表

  1. 将配置、提示词、模型调用、业务校验和 Web 路由分层,避免把所有逻辑堆进一个脚本。
  2. 对外部输入做长度、类型和授权检查;把检索到的文档当作数据,不当作有权改变程序规则的指令。
  3. 给模型调用设置超时、并发上限和费用/Token 预算;取消请求时关闭连接。
  4. 对 JSON 等结构化输出做字段与类型验证,不能因 Prompt 要求了 JSON 就跳过校验。
  5. 为成功、空结果、无权限、超时、限流、无效响应都设计不同且不泄密的返回路径。
  6. 用固定评测样例检查提示词或模型变更;上线后观察错误率、延迟、成本和用户反馈。

详细语法见 Python基础与AI应用;机器学习术语见 机器学习与深度学习基础。服务商 SDK 与平台 API(接口)会变化,复制示例前按实际锁定版本查看官方文档。

相关笔记

  • Python基础与AI应用
  • 机器学习与深度学习基础
  • RAG检索增强生成
  • Agent与Dify基础

参考资料

  • 《Python+AI 从入门到大神一套通关》:AI 应用、网络机器人、数据分析及 Web 开发课件。
  • 《AI 大模型 RAG 与 Agent 智能体项目实战开发》:提示词工程、RAG 开发和项目课件。
  • 安全原则:不收录来源课件中的密钥样式示例。

原始来源文件

以下列出本篇整理所依据的代表性原件;同主题重复版本与完整状态请查阅 source-manifest.csv。

  • Raw sources/AI大模型RAG与Agent智能体项目实战开发/资料/数据资料/Python基础语法.txt
  • Raw sources/Python+AI从入门到大神一套通关/第3章 - Python项目实战之AI应用/PPT/第3章-Python项目实战之AI应用.pptx

放弃未保存的修改?

有未保存的修改,离开会丢失这些内容。