1. 项目缘起与整体设计思路1.1 为什么我要从零手搓一个个人AI助手市面上的AI助手产品已经多到用不过来手机里随便一划就是三五个对话入口。但用久了会发现一个很尴尬的问题它们都很聪明却都不太“懂我”。每次开新对话都要重新交代一遍背景——我是做什么的、习惯用什么语言、输出格式偏好是什么、哪些话题不用展开。这种重复劳动做多了就会冒出一个念头能不能自己搭一个真正属于自己的助手把那些固定的上下文、工具调用、记忆机制全部固化下来这个系列我打算完整记录从零搭建一个个人AI助手的过程标题里的“阶段1”意味着这是一个多阶段项目而这一篇聚焦在最基础的两件事上项目初始化和基础Model I/O。说白了就是把骨架搭起来把“跟模型说一句话、拿回一句话”这条最核心的链路跑通。听起来简单但这一步的地基打得好不好直接决定了后面加记忆、加工具、加多轮编排时会不会推倒重来。适合谁看如果你写过一点代码对API调用不陌生但一直停留在“调个接口试试”的阶段想认真做一个能长期迭代的个人项目那这篇的节奏应该刚好。如果你完全没接触过也没关系我会把每个选择背后的理由讲清楚你照着抄作业也能跑起来。1.2 阶段1到底要解决什么问题很多人做个人项目容易犯一个毛病一上来就想把终极形态想清楚结果设计了两周架构一行能跑的代码都没有。我踩过这个坑所以这次刻意把阶段1的范围压到最小。它只解决三件事项目能跑起来有清晰的目录结构、依赖管理、配置管理换台机器clone下来就能用。能稳定地和模型对话封装一个统一的Model I/O层把请求、响应、错误处理、重试都收拢到一个地方。为后续扩展留好接口记忆、工具、多轮对话这些后面要加的东西在这一步就要预留好插槽而不是等加的时候再大改。这三件事看起来朴素但每一件都有讲究。比如“统一Model I/O层”这个设计如果一开始不封后面每加一个功能就到处散落着API调用代码改一个参数要全局搜索替换那才叫痛苦。所以阶段1的核心思路就是把变化的部分隔离出来把稳定的部分固化下来。1.3 技术选型背后的取舍逻辑选型这块我不打算堆一堆框架名字显得很专业而是说说我为什么这么选。语言用Python理由很直接AI生态的库最全调试方便写原型快。虽然性能不是最强但个人助手这种场景对性能不敏感开发效率才是第一位的。模型接口层我选择自己封装一个薄薄的适配层而不是直接用某个大而全的框架。原因是我试过几个现成的Agent框架它们确实开箱即用但抽象层次太厚出了问题很难定位到底是框架的锅还是模型的锅。自己封装虽然多写几十行代码但每一行都在自己掌控里调试的时候心里有底。配置管理用环境变量加一个配置文件的双层结构。敏感信息比如API密钥走环境变量不进代码库非敏感的默认参数比如默认模型、超时时间走配置文件方便版本管理和团队共享。这个习惯是从无数次“密钥不小心提交到仓库”的教训里养成的。目录结构上我坚持一个原则按职责分层不按功能分文件。也就是说所有跟模型交互相关的代码放一个目录所有跟配置相关的放一个目录而不是按“聊天功能”“总结功能”这样切。因为后者在项目变大后会导致同一个底层逻辑散落在多个文件里维护起来很痛苦。2. 项目初始化的核心细节与实操要点2.1 目录结构怎么设计才不后悔先上我最终采用的目录结构然后逐个解释为什么这么放personal-assistant/ ├── config/ │ ├── settings.yaml │ └── prompts/ ├── src/ │ ├── core/ │ │ ├── model_io.py │ │ ├── config_loader.py │ │ └── exceptions.py │ ├── utils/ │ │ └── logger.py │ └── main.py ├── tests/ │ └── test_model_io.py ├── .env.example ├── .gitignore ├── requirements.txt └── README.mdconfig/放配置和提示词模板。提示词单独抽出来是因为它们会频繁调整混在代码里改起来很烦而且抽出来后可以做成模板文件支持变量替换。src/core/是核心中的核心model_io.py负责所有跟模型打交道的事config_loader.py负责读配置exceptions.py定义自己的异常类型。把异常单独定义是个好习惯后面做错误处理时能精确区分“是网络问题”还是“是配置问题”还是“是模型返回格式不对”。src/utils/放通用工具目前只有日志。日志这块我强烈建议一开始就配好不要用print调试因为后面多轮对话、工具调用的时候你需要看到完整的请求链路print根本不够用。tests/哪怕阶段1只写一个测试也要把目录建起来。测试的意义不只是验证正确性更是逼你把接口设计得可测试——如果一个函数很难写测试往往说明它的职责太杂了。注意不要一上来就搞微服务或者过度分层。个人项目最大的敌人是复杂度目录结构够用就行等真的痛了再重构。2.2 依赖管理与环境隔离的实操细节依赖管理我用最朴素的requirements.txt没用Poetry或Pipenv。不是它们不好而是阶段1的依赖就那么几个用重工具反而增加心智负担。等依赖多到需要锁版本、分环境的时候再迁移也不迟。虚拟环境是必须的这点没有商量余地。我见过太多人因为懒得建虚拟环境把系统Python搞得一团糟最后重装系统。命令很简单python -m venv venv source venv/bin/activate # Windows下是 venv\Scripts\activate pip install -r requirements.txtrequirements.txt里我建议锁定主版本号而不是精确到补丁号。比如写httpx0.27,0.28而不是httpx0.27.0。原因是补丁版本通常只是修bug自动升级风险低而主版本升级往往有破坏性变更需要手动确认。这个策略在长期项目里能省很多事。.gitignore一定要在第一次提交前就写好至少包含venv/ .env __pycache__/ *.pyc .pytest_cache/.env被忽略是铁律同时提供一个.env.example作为模板里面只写键名不写真实值。这样别人clone下来知道要配哪些变量又不会泄露任何敏感信息。2.3 配置加载的分层策略配置我分了三层优先级从高到低环境变量最高优先级用于敏感信息和部署时的临时覆盖。配置文件settings.yaml放默认参数进版本库。代码内默认值兜底保证即使配置缺失也能跑起来。config_loader.py的核心逻辑就是按这个顺序查找找到就用找不到就往下走。这样设计的好处是本地开发时改配置文件就行部署到服务器时用环境变量覆盖代码完全不用动。一个容易忽略的细节是配置的类型校验。比如超时时间应该是数字如果配置文件里手滑写成了字符串不校验的话会在运行时才报错而且报错信息可能很隐晦。所以我在加载时加了一层轻量校验类型不对就立刻抛出带明确信息的异常。这几十行代码能省下未来无数个小时的排查时间。# config_loader.py 核心片段示意 def load_config(): config load_yaml(config/settings.yaml) config[api_key] os.getenv(ASSISTANT_API_KEY, config.get(api_key)) config[timeout] int(os.getenv(ASSISTANT_TIMEOUT, config.get(timeout, 30))) if not config[api_key]: raise ConfigError(API密钥未配置请检查环境变量或配置文件) return config提示配置项命名统一加前缀比如ASSISTANT_避免和其他工具的环境变量冲突。这个坑我在一个项目里踩过两个库用了同一个变量名排查了半天。3. 基础Model I/O的封装与实现3.1 为什么必须封装一层Model I/O直接调API不是不行但你会很快发现几个问题每个调用点都要处理超时、重试、错误码换个模型供应商要改所有调用点想加个日志记录请求耗时得在每个地方重复写。这些都是典型的“横切关注点”散落在业务代码里就是灾难。封装的核心目标是收敛变化。把“怎么跟模型通信”这件事关在一个盒子里外面的人只需要说“给我一段回复”不关心底层是HTTP还是SDK不关心重试了几次。这样将来换模型、加缓存、加限流都只改这一个文件。我设计的接口非常克制阶段1只有两个方法chat(messages, **kwargs)输入消息列表返回模型回复。chat_stream(messages, **kwargs)流式版本逐块返回。为什么先做这两个因为非流式和流式覆盖了绝大多数场景。非流式适合后台任务、批处理流式适合交互式对话用户体验好。其他花哨的功能等真需要了再加。3.2 请求构造与消息格式的规范化消息格式我统一成OpenAI风格的结构因为这是事实标准各家模型基本都兼容或容易转换messages [ {role: system, content: 你是一个简洁的助手}, {role: user, content: 帮我解释一下什么是幂等性} ]role只有三种system、user、assistant。这个约束很重要不要自己发明角色名否则换模型时会很麻烦。请求构造时有个细节值得说参数合并的顺序。我采用“默认参数 → 配置文件参数 → 调用时传入参数”的覆盖顺序。这样调用方可以临时覆盖某个参数比如这次想要更长的输出而不影响全局默认。实现上用字典的update链就能搞定但要注意深拷贝避免修改默认字典污染后续调用。def _build_params(self, **overrides): params dict(self.default_params) # 拷贝不污染原字典 params.update(overrides) return params超时设置我建议分两级连接超时和读取超时。连接超时短一点比如5秒因为连不上就是连不上等太久没意义读取超时长一点比如60秒因为模型生成长文本确实需要时间。很多库默认只有一个总超时自己封装时可以拆开控制体验会好很多。3.3 响应解析与错误处理的完整链路响应解析看起来简单其实坑不少。模型返回的内容可能为空、可能被截断、可能包含意料之外的字段。我的处理原则是永远不要假设响应结构完全符合预期。解析时先检查HTTP状态码非200直接归类为网络或服务错误。然后检查响应体里是否有错误字段有些服务即使返回200也会在body里带错误信息。最后提取内容时如果内容为空要区分是“模型真的返回空”还是“解析路径错了”这两种情况的处理方式完全不同。错误处理我分了四类对应不同的重试策略错误类型典型场景是否重试处理方式网络错误连接超时、DNS失败是指数退避重试3次限流错误429状态码是等待指定时间后重试客户端错误400参数错误、401鉴权失败否直接抛出需人工修复服务端错误500、502是重试2次仍失败则抛出指数退避的实现很简单但效果显著。第一次等1秒第二次等2秒第三次等4秒加上一点随机抖动避免多个请求同时重试造成雪崩。这个模式我在多个项目里用过能挡掉大部分偶发的网络抖动。def _retry_with_backoff(self, func, max_retries3): for attempt in range(max_retries): try: return func() except RetryableError as e: if attempt max_retries - 1: raise wait (2 ** attempt) random.uniform(0, 1) logger.warning(f第{attempt1}次重试等待{wait:.1f}秒) time.sleep(wait)注意重试一定要区分错误类型。对400这种参数错误重试是毫无意义的只会浪费时间。我见过有人无脑重试所有错误结果一个配置错误重试了十几次日志刷屏还找不到真正原因。3.4 流式响应的处理要点流式响应是提升交互体验的关键但处理起来比非流式麻烦。核心难点在于数据是一块一块来的每块可能不完整需要自己拼接和解析。我用的是逐行读取的方式每行以特定前缀开头比如data:遇到结束标记就停止。解析时要注意几个坑空行要跳过、结束标记要正确处理、网络中断时要能优雅退出而不是卡死。def chat_stream(self, messages, **kwargs): params self._build_params(streamTrue, **kwargs) with self._client.stream(POST, self.endpoint, jsonparams) as response: for line in response.iter_lines(): if not line: continue if line.startswith(data: ): data line[6:] if data [DONE]: break chunk json.loads(data) content chunk[choices][0][delta].get(content, ) if content: yield content流式接口设计成生成器generator是最自然的调用方用for chunk in assistant.chat_stream(...)就能逐块处理。这样无论是打印到终端还是推送到前端都很灵活。一个实操心得流式场景下错误处理要特别小心因为响应头可能已经发出去了这时候再抛异常调用方可能已经处理了一半数据。我的做法是在流开始前做好所有校验流开始后如果出错就发送一个特殊的错误块让调用方识别而不是直接抛异常。4. 常见问题与排查技巧实录4.1 初始化阶段的典型报错与解决问题一模块导入失败提示ModuleNotFoundError。这个九成是虚拟环境没激活或者依赖没装全。排查顺序先确认which python指向的是虚拟环境里的解释器再pip list看依赖是否都在。如果都正常还报错检查一下是不是文件名和标准库重名了比如你建了个json.py那导入标准库json就会失败。这个坑很隐蔽我中过一次找了半小时。问题二配置文件读取不到用了默认值但没报错。这通常是因为配置文件路径用了相对路径而运行时的工作目录不是项目根目录。解决办法是用pathlib.Path(__file__).parent来定位基于文件自身位置计算路径而不是基于当前工作目录。这样无论从哪里运行都不会出错。from pathlib import Path CONFIG_PATH Path(__file__).parent.parent / config / settings.yaml问题三环境变量明明设了却读不到。检查两点一是设置环境变量的终端和运行程序的终端是不是同一个二是变量名有没有拼写错误大小写敏感。在Linux和macOS上export只在当前终端会话有效换个终端就没了。想持久化要写进shell配置文件。4.2 Model I/O调用中的高频故障故障一请求超时但不确定是网络问题还是模型太慢。我的排查方法是先单独测网络连通性用一个极简的请求比如只发一个字符看响应时间。如果极简请求也超时那是网络或服务端问题如果极简请求很快但完整请求超时那是模型生成慢需要调大读取超时。这个二分法能快速定位问题所在。故障二返回内容被截断句子说到一半就没了。这通常是max_tokens设小了。注意max_tokens限制的是输出长度不包括输入。如果你不确定该设多少可以先设大一点比如4096观察实际输出长度后再调整。另外有些模型有上下文总长度限制输入太长也会导致输出空间被压缩。故障三偶发的429限流重试后还是失败。429说明触发了服务端的频率限制。除了重试更根本的解决办法是加一个本地限流器控制请求速率。简单的做法是用令牌桶算法每秒放行固定数量的请求。这个在阶段1可以先不做但如果你的助手会批量处理任务建议早点加上。故障四流式响应偶尔卡住不返回。流式场景下如果服务端长时间不发送数据连接可能被中间层断开。解决办法是设置一个“块间超时”如果超过一定时间没收到新块就主动断开并重连。这个超时不能设太短否则正常的生成间隔也会被误判。4.3 我踩过的坑与独家避坑技巧坑一日志里打印了完整的API密钥。调试时图方便直接logger.info(f请求参数{params})结果密钥明文进了日志文件。后来我养成了习惯打印前先过一遍脱敏函数把密钥、token这类字段替换成***。这个习惯救过我一次因为日志文件不小心被同步到了共享目录。坑二异常捕获太宽泛掩盖了真正的bug。一开始我图省事用except Exception一把抓结果一个拼写错误被当成网络错误重试了三次最后报了个莫名其妙的错。后来改成精确捕获只捕获预期的异常类型其他的一律让它抛出来。这样bug暴露得快修得也快。坑三默认参数用了可变对象。Python里默认参数如果是列表或字典会在函数定义时求值一次后续所有调用共享同一个对象。我写过一个def chat(messages, history[])结果历史记录在所有会话间串了。正确做法是用None做默认值函数内部再初始化。坑四忽略了响应的编码问题。有次返回的中文全是乱码查了半天发现是响应头里的编码声明和实际编码不一致。解决办法是显式指定用UTF-8解码不要依赖自动检测。这个在跨平台时尤其重要。提示建议在阶段1就写一个简单的冒烟测试脚本每次改完代码跑一遍确认基本链路是通的。这个脚本不用复杂能发一条消息、收到回复、打印出来就行。它的价值在于给你一个快速的信心反馈避免改了半天发现基础功能坏了。5. 阶段1的验收标准与后续扩展方向5.1 怎么判断阶段1算完成了我不喜欢用“感觉差不多了”来判断一个阶段是否完成而是定几个可验证的标准在一台全新的机器上按README的步骤操作能在10分钟内跑通第一个对话。配置文件缺失关键项时能给出明确的错误提示而不是莫名其妙的崩溃。网络抖动时能自动重试最终成功或给出清晰的失败原因。流式和非流式两种模式都能正常工作。有一个测试用例覆盖核心的请求-响应链路。这五条都满足阶段1就算扎实了。特别是第一条它逼你把文档和依赖管理做好这个习惯在长期项目里价值巨大。5.2 为阶段2预留的扩展点阶段1虽然简单但我在设计时已经为后面留了插槽。model_io.py里的chat方法签名预留了**kwargs将来加工具调用、加记忆注入都可以通过参数传进去不用改接口。config/目录下的prompts/文件夹目前是空的但结构已经在了阶段2做提示词工程时直接往里加文件就行。异常体系也是为扩展准备的。现在只有基础的几类异常后面加工具调用时会遇到“工具执行失败”“工具返回格式错误”等新情况直接继承现有基类加子类即可调用方的错误处理逻辑不用大改。我个人在实际操作中的体会是阶段1最容易被低估很多人觉得“不就是调个接口嘛”草草了事结果后面每加一个功能都要回头补基础设施的债。把这一步做扎实后面加记忆、加工具、加多轮编排时你会发现大部分时间都花在真正的业务逻辑上而不是在跟基础设施的坑较劲。这个投入产出比做过的人都懂。