AI 应用开发的脚手架搭建之旅

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

目标：在本地拥有一套 Python 3.10+、VSCode、Git、Conda 组成的开发环境。

踩坑记录：

Windows 还是 Linux？ 其实都行，但 Windows 下 Git Bash 对路径的处理偶尔会和 CMD 不一样，比如 conda activate 在 PowerShell 和 CMD 中表现不一致。我最终选择在 Windows Terminal 中统一使用 PowerShell，并执行 conda init powershell 解决了激活问题。

SSH Key 的权限问题：生成 id_ed25519 后，ssh -T 始终提示 Permission denied (publickey)。排查发现是我把公钥粘贴到 GitHub 时多复制了一个换行符。教训：复制公钥后先在文本编辑器里检查一下，确保是完整的一行。

Conda 下载慢：默认源在国外，conda create 时速度感人。解决方案：添加清华镜像源，在 ~/.condarc 中配置 channels，之后速度飞起。

📦 二、API 密钥管理：代码里绝不再写明文

目标：将 API Key 从代码中剥离，使用 .env 文件管理。

踩坑记录：

一开始我在 simple_chat.py 中直接写了 api_key = “sk-xxx”，还顺手 git add 了。虽然仓库是 private 的，但职业习惯告诉我这样不行。于是紧急补救： bash

git rm –cached simple_chat.py # 从暂存区移除 echo “.env” >> .gitignore # 创建忽略文件 git add .gitignore git commit –amend # 修正上一次提交

教训：项目初始化第一步就应该是创建 .gitignore 并写入 .env，而不是等到代码写完再补。

🌿 三、Git 进阶：让提交历史成为你的日记

目标：掌握 branch、merge、rebase、stash 的日常用法。

踩坑记录：

git rebase 的惊魂一刻：我兴冲冲地想把 feature/daily-log 分支 rebase 到最新的 main 上，结果忘了自己已经在远程推送过这个分支。rebase 后强制推送（git push -f）虽然成功，但看到同事（其实是自己另一个终端模拟的）拉取代码时报错，我才意识到公共分支禁止 rebase 这条铁律。

git stash 救场：写了一半的异步客户端代码，突然要切到 main 去修一个 README 的错别字。git stash 把工作区存起来，切分支修完再 git stash pop，完美恢复现场。这个命令现在已经成为我的高频操作。

🧪 四、API 封装：从裸调 SDK 到自己造轮子

目标：封装一个支持重试、错误处理、同步/异步的 API 客户端。

踩坑记录：

官方 SDK 的坑：通义千问的 dashscope SDK 在 Windows 下偶尔会报 SSL 证书错误，而用 requests 直接调 API 反而稳定。于是决定自己基于 requests 封装，顺带练习 HTTP 细节。

重试策略的选择：一开始用 for 循环写死重试 3 次，后来发现 tenacity 这个库，几行装饰器就搞定了指数退避重试，代码简洁多了。

异步与 aiohttp 的 session 管理：异步客户端中，如果每次请求都 aiohttp.ClientSession() 新建一个 session，会报 Unclosed client session 警告。正确做法是实现 aenter 和 aexit，在上下文管理器内复用 session。

智谱 API 的响应格式差异：通义千问返回的是 output.text，智谱返回的是 choices[0].message.content。封装时要做统一处理，不然上层调用会一脸懵。

📝 五、博客草稿：《AI 应用开发环境搭建与 API 调用》

作为一名刚从自动化测试转向 AI 应用开发的新人，我深知第一步的环境搭建有多劝退。这篇文章记录了我如何在一周内从零搭建 Python 环境、配置 Git、管理 API 密钥，并最终封装出一个支持多模型、带重试和异步调用的 API 客户端。希望对同样在路上的你有所帮助。

环境准备：选 Windows 还是 Linux？

Python 3.10+ （务必勾选 “Add to PATH”）

VSCode + Python 插件

Git + 配置 SSH Key 到 GitHub

Miniconda （比 Anaconda 轻量）

坑点速览

Conda 激活失败：运行 conda init 并重启终端。

SSH 连接 GitHub 失败：检查公钥是否完整粘贴，并确认使用而非 https 地址。

密钥管理：.env 是你的好朋友

千万不要把 API Key 写死在代码里！正确姿势：

项目根目录创建 .env 文件： text

OPENAI_API_KEY=sk-xxx ZHIPU_API_KEY=xxx

创建 .gitignore，第一行写上 .env。

使用 python-dotenv 加载： python

from dotenv import load_dotenv import os load_dotenv() api_key = os.getenv(“OPENAI_API_KEY”)

Git 工作流：分支、合并与储藏

在单人项目中养成良好习惯，多人协作时才不会手忙脚乱。

分支策略：main 分支只放稳定代码，新功能一律切 feature/xxx 分支。 合并还是变基？ 本地私有分支用 rebase 保持历史整洁；公共分支只用 merge。
 git stash：当你写到一半需要紧急切换分支时，它就是你的救星。

封装一个健壮的 API 客户端

官方 SDK 虽好，但自己动手封装能加深对 HTTP 和重试机制的理解。我封装了一个 APIClient 基类，实现了：

自动添加 Authorization 头 超时设置
 基于 tenacity 的指数退避重试
 同步/异步双版本（异步用 aiohttp）

from tenacity import retry, stop_after_attempt, wait_exponential

踩坑集锦与解决方案
问题解决方案
conda 下载慢配置国内镜像源（清华、阿里云）
aiohttp 警告未关闭 session 使用 async with 上下文管理器
智谱 API 返回 error 而非 choices 检查 model 名称是否正确，如 glm-4-flash 免费
Git 提交了敏感信息 git reset –soft HEAD~1 或 git filter-branch

AI 应用开发的脚手架搭建之旅

相关推荐