1. 项目缘起与整体设计思路1.1 为什么我要从零搭一个个人AI助手市面上的AI对话产品已经多到用不过来但我始终觉得少了点什么。通用助手什么都懂一点却对我的工作习惯、常用术语、项目上下文一无所知。每次开新对话都要重新交代背景就像跟一个记忆力只有七秒的同事协作。于是我决定动手做一个属于自己的AI助手从最基础的骨架开始逐步往里填能力。这个系列我打算分阶段推进阶段1只做两件事项目初始化和基础Model I/O。听起来简单但这两步决定了后面所有功能的扩展性。很多人在这一步图省事随手写个脚本调一下接口就完事结果到阶段3想加记忆、加工具调用时发现代码结构根本撑不住只能推倒重来。我不想踩这个坑所以阶段1我会把工程结构、配置管理、模型输入输出的抽象层都搭好。这篇文章面向的读者是有一点编程基础、想自己动手做AI助手但不知道从哪下手的人。你不需要是架构师但至少要能看懂Python代码、知道什么是API调用。如果你已经做过类似项目也可以看看我在结构设计上的取舍或许有值得借鉴的地方。1.2 阶段1的边界划定做什么和不做什么动手之前先划边界这是我做任何项目的习惯。阶段1的目标非常克制做搭好项目目录结构、配置管理、依赖管理、模型调用的统一接口、基础的输入输出处理。不做不做对话历史持久化、不做工具调用、不做RAG检索、不做多模型路由、不做前端界面。为什么这么划因为个人项目最容易死在“想一口气做完”上。我见过太多人第一天兴致勃勃列了二十个功能第三天就烂尾了。阶段1的核心价值是建立一个能跑通的最小闭环你输入一句话模型返回一句话整个链路是通的而且代码结构是干净的、可扩展的。这里有个关键决策Model I/O层要不要做抽象有人觉得阶段1就调一个模型直接写死不就完了。我的选择是做一层薄抽象。原因很简单——你几乎不可能永远只用一个模型。今天用这个明天可能想换那个对比效果后天可能想同时调两个做投票。如果一开始就把模型调用散落在业务代码里后面换模型就是灾难。薄抽象的成本很低但收益在阶段2、阶段3会指数级放大。1.3 技术选型背后的考量技术栈的选择我遵循一个原则用我最熟的工具而不是最时髦的工具。个人项目不是炫技场能快速跑起来、方便调试、出问题好排查才是第一位的。语言Python。AI生态最完善几乎所有模型厂商都优先支持Python SDK遇到问题搜索到的答案也最多。包管理用venv pip不上poetry或conda。个人项目依赖不多venv足够而且零学习成本。poetry虽然优雅但多一层抽象就多一个出问题的地方。配置管理环境变量 .env文件。API密钥绝对不能硬编码在代码里这是铁律。用python-dotenv读取.env文件既安全又方便切换环境。HTTP客户端用官方SDK不自己裸写requests。官方SDK帮你处理了重试、超时、流式解析这些脏活没必要重复造轮子。注意.env文件一定要加到.gitignore里。我见过有人把带密钥的代码推到公开仓库结果被人扫到密钥刷了几百块的账单。这种事一次就够你记住一辈子。2. 项目初始化实操从空目录到可运行骨架2.1 目录结构设计与理由先看最终要搭出来的目录结构personal-ai-assistant/ ├── .env # 环境变量不提交 ├── .env.example # 环境变量模板提交 ├── .gitignore ├── requirements.txt ├── README.md ├── config/ │ └── settings.py # 配置加载与校验 ├── core/ │ ├── __init__.py │ ├── model_client.py # 模型调用抽象层 │ └── message.py # 消息数据结构 ├── utils/ │ ├── __init__.py │ └── logger.py # 日志工具 └── main.py # 入口跑通最小闭环这个结构不复杂但每一层都有明确职责。config管配置core管核心逻辑utils管通用工具main.py只负责串起来。为什么要把model_client和message分开因为消息结构是跨模型通用的而客户端是跟具体模型绑定的。分开之后换模型只需要改客户端消息结构不动。我特别想强调message.py这个文件。很多人调API就是随手拼个dict传进去短期没问题但当你需要处理多轮对话、系统提示词、不同角色的消息时散落的dict会让你疯掉。用一个数据类把消息结构固定下来后面加任何功能都有统一的入口。2.2 环境准备与依赖安装第一步创建项目目录并初始化虚拟环境mkdir personal-ai-assistant cd personal-ai-assistant python -m venv venv source venv/bin/activate # Windows用 venv\Scripts\activate第二步写requirements.txt。阶段1的依赖非常少python-dotenv1.0.1 openai1.30.0这里只列了两个。python-dotenv负责读.envopenai是官方SDK。你可能会问为什么用openai的SDK而不是别的因为现在很多模型服务都兼容OpenAI的接口格式用这个SDK可以一套代码对接多个服务只需要改base_url和model名。这是阶段1做抽象的一个隐藏红利。第三步安装依赖pip install -r requirements.txt实操心得建议把版本号写死不要用。我吃过亏某次SDK小版本升级改了返回结构代码直接报错排查了半天才发现是依赖自动升级了。写死版本号升级时手动改心里有数。2.3 配置管理密钥安全与多环境切换.env.example是模板提交到仓库内容长这样OPENAI_API_KEYyour_api_key_here OPENAI_BASE_URLhttps://api.openai.com/v1 DEFAULT_MODELgpt-4o-mini REQUEST_TIMEOUT30 MAX_RETRIES3.env是你本地的真实配置从example复制一份改掉密钥即可。config/settings.py负责加载和校验import os from dotenv import load_dotenv load_dotenv() class Settings: def __init__(self): self.api_key os.getenv(OPENAI_API_KEY) self.base_url os.getenv(OPENAI_BASE_URL, https://api.openai.com/v1) self.default_model os.getenv(DEFAULT_MODEL, gpt-4o-mini) self.timeout int(os.getenv(REQUEST_TIMEOUT, 30)) self.max_retries int(os.getenv(MAX_RETRIES, 3)) self._validate() def _validate(self): if not self.api_key: raise ValueError(OPENAI_API_KEY 未配置请检查 .env 文件) if self.timeout 0: raise ValueError(REQUEST_TIMEOUT 必须为正数) settings Settings()这段代码的关键在于_validate方法。配置错误要在启动时就暴露而不是等到第一次调用API才报错。我见过太多项目把配置校验拖到运行时结果用户点了按钮才弹错误体验极差。启动即校验快速失败这是好习惯。2.4 日志工具为后续调试铺路utils/logger.py很简单但必须有import logging import sys def get_logger(name: str) - logging.Logger: logger logging.getLogger(name) if not logger.handlers: handler logging.StreamHandler(sys.stdout) formatter logging.Formatter( %(asctime)s | %(levelname)s | %(name)s | %(message)s ) handler.setFormatter(formatter) logger.addHandler(handler) logger.setLevel(logging.INFO) return logger为什么阶段1就要加日志因为模型调用是黑盒出问题时你只能靠日志还原现场。请求发了什么、返回了什么、耗时多久这些信息在调试时价值千金。等到出问题才加日志往往已经错过了现场。3. 基础Model I/O实现抽象层与消息结构3.1 消息数据结构设计core/message.py定义消息的数据结构from dataclasses import dataclass, field from typing import Literal, List Role Literal[system, user, assistant] dataclass class Message: role: Role content: str def to_dict(self) - dict: return {role: self.role, content: self.content} dataclass class Conversation: messages: List[Message] field(default_factorylist) def add(self, role: Role, content: str) - Conversation: self.messages.append(Message(rolerole, contentcontent)) return self def to_payload(self) - List[dict]: return [m.to_dict() for m in self.messages]Conversation类用了链式调用设计add返回self这样可以连续写conv.add(system, ...).add(user, ...)。这个设计在阶段2加多轮对话时会很顺手。to_payload方法负责把内部结构转成API需要的格式转换逻辑集中在一处改起来方便。注意role的类型用了Literal限定为三种。不要小看这个限定它能防止你手滑写成uesr这种拼写错误。类型检查工具会直接报错比运行时才发现强得多。3.2 模型客户端抽象层core/model_client.py是阶段1的核心from openai import OpenAI from config.settings import settings from core.message import Conversation from utils.logger import get_logger logger get_logger(__name__) class ModelClient: def __init__(self): self.client OpenAI( api_keysettings.api_key, base_urlsettings.base_url, timeoutsettings.timeout, max_retriessettings.max_retries, ) self.model settings.default_model def chat(self, conversation: Conversation) - str: payload conversation.to_payload() logger.info(f请求模型{self.model}, 消息数{len(payload)}) try: response self.client.chat.completions.create( modelself.model, messagespayload, ) content response.choices[0].message.content logger.info(f响应成功, 长度{len(content)}) return content except Exception as e: logger.error(f模型调用失败: {e}) raise这个类做了几件事初始化客户端、封装chat方法、记录日志、处理异常。为什么把异常重新抛出而不是吞掉因为调用方需要知道失败了才能决定是重试还是提示用户。吞异常是万恶之源出了问题连日志都看不到。max_retries参数交给SDK处理它会自动对可重试的错误如超时、限流进行退避重试。这比你自己写重试逻辑靠谱得多因为SDK知道哪些错误该重试、哪些不该。3.3 流式输出为什么阶段1就要支持基础的非流式调用已经能跑通但我建议阶段1就把流式输出加上。原因很实际用户体验。非流式调用要等模型生成完整回复才返回长回复可能等十几秒用户会以为程序卡死了。流式输出边生成边显示感知延迟大幅降低。def chat_stream(self, conversation: Conversation): payload conversation.to_payload() logger.info(f流式请求模型{self.model}) stream self.client.chat.completions.create( modelself.model, messagespayload, streamTrue, ) for chunk in stream: delta chunk.choices[0].delta.content if delta: yield delta流式版本返回一个生成器调用方可以逐块处理。注意delta.content可能是None比如第一个chunk只包含role信息所以要判空。这个细节不处理会直接报TypeError是新手常踩的坑。3.4 入口文件跑通最小闭环main.py把所有东西串起来from core.message import Conversation from core.model_client import ModelClient def main(): client ModelClient() conv Conversation() conv.add(system, 你是一个简洁、专业的个人助手。) conv.add(user, 用三句话解释什么是API。) print( 非流式 ) print(client.chat(conv)) print(\n 流式 ) conv.add(assistant, client.chat(conv)) conv.add(user, 再举一个生活中的例子。) for chunk in client.chat_stream(conv): print(chunk, end, flushTrue) print() if __name__ __main__: main()跑起来之后你会看到非流式一次性输出流式逐字输出。到这里阶段1的目标就达成了一个结构清晰、可扩展、能跑通的最小闭环。4. 常见问题与排查技巧实录4.1 模型调用高频问题速查表问题现象可能原因排查方向401 Unauthorized密钥错误或未加载检查.env是否存在、密钥是否有多余空格404 Not Foundbase_url或model名错误确认服务地址和模型名拼写超时无响应网络问题或超时设置过短调大REQUEST_TIMEOUT检查网络连通性返回内容为空模型被内容策略拦截打印完整response对象查看finish_reason流式输出乱码编码问题确认终端编码为UTF-8429 Too Many Requests触发限流降低频率SDK会自动退避重试这张表是我实际调试中整理出来的覆盖了九成以上的报错。遇到问题先查表能省大量时间。4.2 三个我踩过的坑坑一.env文件没生效。有次我改了.env里的模型名但程序还是用旧的。排查发现是load_dotenv()在模块导入时执行而我改文件后没重启程序。环境变量是进程启动时读取的改完必须重启。这个坑很隐蔽因为代码看起来完全正确。坑二流式输出在IDE里不显示。在某个IDE的运行窗口里流式输出会攒到最后一次性显示看起来跟非流式一样。我一度以为流式没生效后来换到终端跑才发现是IDE的缓冲问题。调试流式一定要用真实终端。坑三消息顺序搞反。有次我把assistant的消息加到了user前面模型返回的内容驴唇不对马嘴。多轮对话的消息顺序必须是system → user → assistant → user → assistant这样交替顺序错了模型会困惑。建议在Conversation.add里加个顺序校验防患于未然。4.3 阶段1的验收标准怎么判断阶段1做完了我给自己定了三条标准换一个模型服务只需要改.env里的base_url和model名代码一行不动。新增一种消息角色比如未来的function角色只需要改message.py。任何一次调用失败日志里能完整还原请求参数和错误信息。这三条都满足阶段1才算合格。如果换模型要改代码说明抽象没做到位如果加角色要改多处说明结构有问题如果出错查不到原因说明日志不够。5. 阶段1之后可以怎么扩展阶段1的骨架搭好之后阶段2我打算加对话历史持久化用SQLite存消息这样重启程序对话不丢。再往后是工具调用让助手能查天气、算数、读文件。这些扩展之所以能顺畅进行全靠阶段1把Model I/O抽象层和消息结构打好了底子。我个人在实际操作中的体会是个人项目最怕的不是功能少而是结构乱。阶段1看起来只做了最基础的事但正是这些基础决定了项目能走多远。如果你也在做类似的东西建议别急着堆功能先把这一层做扎实。后面每加一个功能你都会感谢现在的自己。最后分享一个小技巧把main.py里的测试对话换成你真实的工作场景比如让它帮你总结一段会议记录、解释一段代码。用真实需求驱动开发比用你好世界测试有意思得多也更容易发现设计上的不足。
