1. 项目概述回归本质的AI开发学习路径如果你刚开始接触AI应用开发面对铺天盖地的LangChain、LlamaIndex、AutoGen这些框架是不是感觉有点懵不知道该从哪个学起或者学了半天一旦框架更新或者遇到一个框架解决不了的特殊需求就完全不知道该怎么办了。我刚开始的时候也是这样被各种抽象概念和“魔法”般的封装搞得晕头转向直到我决定抛开所有框架直接从最底层的API调用开始学起才真正看清了AI应用开发的本质。这个名为“Learn AI Right”的项目就是我基于这个理念整理的一套学习路径它不依赖任何第三方AI框架只用纯Python和官方API带你从零开始亲手搭建和理解每一个核心功能模块。这个项目的核心价值在于“祛魅”。它把那些被包装得高大上的行业术语比如“智能体”、“记忆”、“RAG”还原成最朴素的编程操作发送HTTP请求、处理JSON数据、维护一个消息列表。学完它你不会成为某个框架的专家但你会成为理解AI应用底层逻辑的专家。无论未来出现什么新框架、新工具你都能快速看透它的本质知道它到底在帮你做什么以及当它出问题时你该如何调试和修复。这套教程非常适合有一定Python基础希望扎实掌握AI应用开发核心原理的开发者无论你是想为自己的产品添加AI功能还是想在这个领域深耕从这里开始都是一个绝佳的选择。2. 核心理念为什么“无框架”学习是更优的起点2.1 框架的“黑箱”困境与基础认知的缺失很多初学者会有一个误区认为使用高级框架是学习的捷径。但事实恰恰相反直接从框架入门往往会让你陷入“黑箱”操作的困境。框架为了提供便利性做了大量的封装和抽象。当你调用agent.run(“查询天气”)时框架在背后可能帮你处理了工具选择、参数提取、API调用、错误重试、结果解析等一系列复杂步骤。这固然方便但同时也屏蔽了所有的实现细节。问题在于当你的应用行为不符合预期时——比如智能体总是调用错误的工具或者RAG检索的结果不相关——你该如何调试如果你只懂框架的API你会束手无策。你只能去翻看框架那可能并不完善的文档或者在社区里寻找是否有其他人遇到了类似的问题。你的调试能力被限制在了框架提供的、有限的日志和配置选项里。而如果你理解底层原理你会清楚地知道这可能是工具函数描述不够清晰、检索的相似度阈值设置不当、或者提示词Prompt的格式有误。你可以像调试普通Python程序一样在每一个环节插入打印语句检查中间数据从而精准定位问题。这个项目的哲学很明确先学会走路再学跑步最后再决定要不要开车。框架就是那辆车它能让你更快到达目的地但如果你连路都不认识一旦车抛锚在荒郊野岭你就彻底迷失了。这里的“走路”就是理解“AI应用 API调用 业务逻辑”这个最基础的等式。只有亲手用最原始的方式实现过聊天记忆、工具调用、文档检索你才能建立坚实的心智模型在未来评估和选用框架时拥有绝对的判断力。2.2 行业术语的“祛魅”与本质还原AI领域充满了创造性的营销词汇它们听起来很酷但也制造了不必要的认知壁垒。这个项目做了一件非常棒的事情就是用大白话和代码把这些术语的底裤给扒了下来。我们来看看它是如何解构的AI智能体 (AI Agents)这听起来非常科幻仿佛有一个自主的、有意识的东西在为你工作。但实际上在当前的架构下一个智能体核心就是一个循环1. 将用户输入和当前状态记忆、工具描述等组合成提示词2. 调用大模型API3. 解析模型的返回如果返回指示要调用某个工具函数就执行对应的Python函数并把结果作为新的上下文回到第1步。它本质上就是一个根据大模型输出决定执行路径的调度器。在项目中你会亲手实现这个调度逻辑。记忆/上下文 (Memory/Context)这是最容易被神秘化的概念。很多教程会教你用各种“记忆存储”方案。但究其根本对于大模型来说“记忆”就是你在每次API调用时附带在请求里的那一系列历史消息。它通常就是一个Python列表列表里每个元素都是一个包含role如user,assistant和content的字典。模型没有真正的记忆它只是基于你这次提供的全部文本即上下文进行生成。项目中的“记忆即列表”模块会让你亲手构建和管理这个列表理解上下文窗口的限制以及如何做摘要压缩。检索增强生成 (RAG)这个词由三部分组成听起来很学术。拆解开来就是1.检索从你的文档库中找到和用户问题最相关的几段文本。2.增强把检索到的文本作为额外的背景信息插入到给模型的提示词中。3.生成模型基于这个“增强”后的提示词生成答案。这里没有任何魔法就是“搜索拼接提问”。项目里你会实现一个最简单的版本用关键词匹配后期可升级为向量搜索进行检索然后通过字符串拼接构造提示词。通过这种祛魅你会发现构建一个AI应用所需要的核心编程技能和你构建一个Web API、一个数据处理脚本并没有本质区别都是数据获取、处理、判断、再输出的过程。大模型只是其中一个能力非凡但接口简单的“外部服务”。3. 十步学习路径深度解析与实操要点这个项目精心设计了一个十步渐进路径每一步都瞄准一个核心模式并且前后依赖层层递进。下面我将带你深入每一步的核心并补充一些原课程中可能未详述的实操细节和心法。3.1 第一步首次AI调用——一切模式的基石核心认知所有复杂的AI应用都始于一次最简单的HTTP POST请求。这一步的目标是消除对API调用的陌生感和恐惧。你会写一个类似下面的Python脚本以OpenAI为例from openai import OpenAI import os client OpenAI(api_keyos.getenv(“OPENAI_API_KEY”)) response client.responses.create( model“gpt-4.1”, input“Hello, what is the capital of France?” ) print(response.output_text)看起来简单但魔鬼在细节里环境变量管理千万不要把API密钥硬编码在代码里。项目使用.env文件这是行业最佳实践。你需要理解python-dotenv库是如何工作的以及为什么这对团队协作和安全性至关重要。响应对象解析response对象是一个结构化的数据。你需要熟悉它的属性比如output_text、id、usage包含token消耗。理解usage是你未来进行成本核算和优化的基础。错误处理网络超时、API额度不足、模型过载……你的代码必须有健壮的错误处理try…except。一开始就要养成习惯考虑API服务不可用时的降级方案或友好提示。实操心得在这一步我建议你故意输错一次API密钥或者把模型名写错看看返回的错误信息是什么。熟悉常见的错误类型和原因是调试能力的起点。3.2 第二步与第三步记忆的两种实现模式记忆即列表这是最根本、最通用的模式。你需要维护一个全局的messages列表。conversation_history [ {“role”: “user”, “content”: “你好我叫小明。”}, {“role”: “assistant”, “content”: “你好小明很高兴认识你”}, ] # 当用户新消息到来时 conversation_history.append({“role”: “user”, “content”: “你还记得我叫什么吗”}) # 调用API时将整个conversation_history作为input发送核心挑战与技巧上下文长度限制模型有最大token限制如128K。长对话会超出限制。解决方案不是框架提供的而是你需要实现的逻辑当历史消息过长时你需要决定是丢弃最老的对话还是对历史进行智能摘要。你可以尝试让AI自己总结之前的对话要点然后将摘要作为一条新的系统消息再附上最近的几条原始对话。系统消息的角色列表的第一条消息通常是role为system的消息用于设定AI的行为准则“你是一个有帮助的助手”。这条消息非常重要它相当于程序的“初始化配置”。记忆与previous_response_id这是OpenAI Responses API提供的一种便利。你不需要手动维护庞大的列表只需要在每次请求时传入上一次响应的idOpenAI的服务端会帮你关联上下文。# 第一次调用 first_response client.responses.create(model“gpt-4”, input“Hello”) # 第二次调用链接到第一次 second_response client.responses.create( model“gpt-4”, input“What did I just say?”, previous_response_idfirst_response.id )注意事项这种方式虽然方便但将状态管理交给了服务端你对对话历史的控制力减弱了。例如你想在中间插入一条自定义的系统提示或者想对历史进行修改会变得比较困难。因此必须先理解并能手写“列表模式”才能正确评估和使用这种便利API的适用场景。3.3 第四步结构化输出——连接非结构化文本与程序逻辑的桥梁大模型默认输出非结构化的文本。但程序需要结构化的数据JSON、字典、对象才能进行下一步处理。结构化输出就是要求模型按照预定格式如JSON Schema返回数据。为什么这步如此关键它是实现“AI作为函数”的关键。想象一下你问AI“分析一下这段用户反馈的情绪和要点。”你希望得到一个如{“sentiment”: “positive”, “key_points”: [“价格合理”, “物流快”]}这样的字典而不是一段需要你再次解析的散文。OpenAI和Anthropic的实现差异OpenAI在Responses API中你可以直接定义response_format{“type”: “json_schema”, “schema”: …}非常直观。Anthropic在项目写作时可能需要通过精心设计的提示词例如要求模型输出特定的JSON标记如json…/json并结合后处理来实现。这里就是一个重要的学习点不同供应商的API设计哲学和功能支持度不同。理解这些差异能帮助你在未来进行多模型适配或迁移时做出合理的设计。实操要点Schema设计要严谨定义清晰的JSON Schema包括字段类型、是否必需、描述。模糊的Schema会导致模型输出不稳定。验证与重试永远不要假设模型返回的数据100%符合格式。必须在代码中添加验证逻辑如使用pydantic库。如果解析失败应设计重试机制例如用更严厉的提示词让模型再试一次。3.4 第五步工具调用——让AI从“思考”到“行动”工具调用或函数调用是AI智能体的核心能力。模型根据你的请求决定要调用哪个工具即你预先注册好的Python函数并生成调用该函数所需的参数。底层机制揭秘你在请求中以特定格式如OpenAI的tools参数向模型描述你可用的工具函数名、描述、参数schema。模型在思考后可能会在响应中返回一个tool_calls的字段表明它想调用某个工具并提供了参数。你的程序不是模型也不是框架需要解析这个响应找到对应的本地Python函数用模型提供的参数执行它。你将函数执行的结果作为一条新的tool角色消息追加到对话历史中然后再次调用模型让它基于工具执行结果继续回答。关键实现细节工具描述的艺术工具的名称和描述至关重要。“get_weather”比“weather”好“获取指定城市的当前天气情况”比“获取天气”好。清晰、具体的描述能极大提高模型选择工具的准确率。参数校验模型生成的参数可能不完整或类型错误。你的工具函数内部必须有严格的参数校验和默认值处理逻辑防止程序崩溃。循环与终止你需要实现一个主循环在“模型生成”和“工具执行”之间反复直到模型输出一个最终面向用户的回答而不是工具调用。你需要设置一个最大循环次数防止出现无限循环。3.5 第六步与第七步RAG及其对话式扩展基础RAG实现文档加载与分块将你的长文档PDF、Word、网页加载为纯文本然后切割成大小适中的“块”。分块大小有讲究太小会丢失上下文太大会引入噪声。通常按段落、按固定字符数如500字或使用更智能的语义分割器。检索项目初期可能使用简单的关键词匹配如TF-IDF。但生产环境更常用向量检索。你需要理解将文本块通过嵌入模型Embedding Model转换为向量一组数字存储到向量数据库。查询时将问题也转换为向量在数据库中寻找最相似的向量即语义最相关的文本块。虽然项目说关键词搜索“够用”但你必须明白向量搜索才是处理语义相似性的标准方案。提示词构建这是RAG效果好坏的决定性因素。一个经典的提示词模板是请基于以下上下文回答问题。如果上下文不包含相关信息请直接说“根据提供的信息无法回答”。 上下文{检索到的文本块} 问题{用户问题} 答案你需要反复调试这个模板比如调整指令的强弱、上下文放置的位置等。对话式RAG这本质上是“记忆”和“RAG”的结合。当用户进行追问时例如“能再详细说说第一点吗”你需要理解当前问题可能指代历史对话中的某个实体“第一点”指的是什么。这可能需要用一个轻量级的模型对当前问题做一次重写将其补充成独立的问题。带着这个完整的问题重新执行一次检索和生成流程。将本次的问答对再追加到对话历史中以维持连贯性。3.6 第八步流式传输——提升用户体验的关键流式传输允许你逐词接收模型的响应而不是等待全部生成完毕。这对于生成长文本时的用户体验至关重要。技术实现API调用会返回一个流式响应对象你可以遍历它。stream client.responses.create(…, streamTrue) for event in stream: if event.type “response.delta”: print(event.delta, end“”, flushTrue) # 逐词打印注意事项前端集成如果你有Web前端需要通过Server-Sent Events (SSE)或WebSocket将后端收到的每个词推送到前端。中间处理在流式传输过程中你很难对尚未完成的输出进行复杂的逻辑判断。如果你的应用需要在生成中途根据已生成内容做出决策设计会变得复杂。3.7 第九步提示词链——复杂工作流的骨架提示词链就是将多个独立的AI调用串联起来前一个的输出作为后一个的输入。这是构建“多智能体”或复杂决策流程的基础。经典模式规划器第一个AI调用分析用户请求将其分解为一系列步骤或子任务。执行器根据规划依次执行各个步骤。每个步骤可能是一个工具调用也可能是一个新的AI调用例如让AI根据某个主题起草大纲。校对/整合器最后一步让AI对所有执行结果进行汇总、润色形成最终答案。实现关键你需要设计好每个环节之间传递数据的格式通常用结构化输出并妥善处理可能发生的错误在某个环节失败时提供回退方案。3.8 第十步毕业项目——综合一切这一步要求你独立设计并实现一个综合应用例如“AI学习教练”。你需要自己定义系统角色教练的性格和职责。工具集教练能做什么查资料出练习题制定计划记忆系统如何记住学生的学习进度和薄弱点RAG知识库教练自身的学科知识库从哪里来交互流程是简单的问答还是多轮诊断和规划这个过程没有标准答案是对你前面所有知识的一次大考。你会遇到设计上的权衡比如响应速度与功能复杂度的平衡这将极大地提升你的工程化思维。4. 环境配置、工具选型与生产级考量4.1 开发环境与依赖管理项目使用requirements.txt管理依赖这是Python项目的基础。但我强烈建议你更进一步使用pyproject.toml配合uv或poetry这类现代工具。它们能更好地管理项目元数据、依赖版本锁定和虚拟环境尤其是在团队协作中。核心依赖解析openai/anthropic官方SDK。务必关注版本更新新版本API可能有重大变化。python-dotenv管理环境变量。确保你的.env文件在.gitignore中永远不要提交密钥。pydantic强烈建议额外学习并引入。用于数据验证和设置管理。你可以用它来定义严谨的配置模型、API请求/响应模型能避免大量低级错误。4.2 超越课程生产环境必须考虑的组件课程教你核心模式但一个可上线的生产系统还需要更多异步编程使用asyncio和aiohttp。用户的请求是并发的同步调用会导致性能瓶颈。你需要学会异步地调用AI API、访问数据库。缓存对相同的提示词进行缓存可以大幅降低成本、提升响应速度。可以使用redis或memcached。限流与降级你的应用依赖外部AI API它们可能限流或不稳定。你需要实现请求队列、重试机制如指数退避并在主要服务不可用时有降级方案如切换备用模型、返回静态提示。监控与可观测性记录每一次调用的耗时、token使用量、费用、成功率。使用像Prometheus和Grafana这样的工具建立仪表盘。这是优化成本和稳定性的眼睛。向量数据库对于严肃的RAG应用你需要一个专业的向量数据库如Pinecone(云服务)、Weaviate(开源)、Qdrant(开源) 或pgvector(PostgreSQL扩展)。它们提供高效的相似度搜索、过滤和可扩展的存储。4.3 提示词工程从技巧到科学课程中你会写很多提示词。请将这些视为需要精心维护和测试的“代码”。结构化与模板化不要将提示词硬编码在业务逻辑中。将它们提取到配置文件如YAML或专门的模板文件中。可以使用Jinja2这样的模板引擎来动态渲染提示词。版本控制与测试提示词的微小改动可能导致输出质量的巨大差异。像对待代码一样对提示词模板进行版本控制并建立测试套件用一批标准问题验证不同版本提示词的效果。思维链与少样本学习在复杂任务中在提示词中要求模型“逐步思考”Let‘s think step by step或者提供几个输入输出的例子Few-shot Learning能显著提升结果的准确性和可靠性。5. 常见问题、调试心法与避坑指南在实际操作中你一定会遇到各种奇怪的问题。下面是我踩过坑后总结的一些排查思路和解决方案。5.1 API调用通用问题问题现象可能原因排查步骤与解决方案认证失败 (401)API密钥错误、过期或未设置。1. 检查.env文件变量名与代码中读取的是否一致。2. 在终端用echo $OPENAI_API_KEY或对应变量验证是否已加载。3. 登录供应商控制台确认密钥有效且有余额。模型不存在 (404) 或 权限错误 (403)模型名称拼写错误或你的账户无权访问该模型如未开放内测。1. 仔细核对模型名注意大小写和连字符。2. 查阅官方文档确认该模型是否已全面开放。上下文长度超限 (400)发送的提示词系统消息用户消息历史消息总token数超过模型限制。1. 计算本次请求的token数可用tiktoken库。2. 实现历史消息截断或摘要功能。响应速度极慢或超时网络问题、模型负载过高、或你请求的模型本身较慢如GPT-4。1. 设置合理的超时参数如timeout30。2. 实现重试逻辑如tenacity库。3. 考虑使用更快的模型如GPT-4o-mini或启用流式响应提升感知速度。5.2 内容生成相关问题问题现象可能原因排查步骤与解决方案AI不遵循指令系统提示词不够明确或位置不对用户消息覆盖了系统指令。1. 强化系统提示词使用“你必须”、“严禁”等强动词。2. 确保系统消息是对话列表的第一条且不会被后续消息覆盖。工具调用不准确工具描述模糊模型对函数参数理解有偏差。1. 优化工具描述使其像清晰的API文档。2. 在提示词中举例说明工具的用法。3. 在代码中对模型返回的参数进行强制类型转换和有效性校验。RAG回答与文档无关检索质量差提示词未强制模型基于上下文。1. 检查检索环节分块大小是否合适向量模型是否匹配相似度阈值是否设得太低2. 强化提示词“必须严格依据以下上下文回答如果上下文未提及请直接说不知道。”结构化输出格式错误JSON Schema定义有歧义模型“幻觉”出额外字段。1. 使用pydantic严格验证输出失败则重试。2. 在提示词中要求模型“输出仅包含指定字段的JSON不要有任何额外解释”。5.3 调试心法打印中间状态这是最强大的调试手段。在关键步骤如调用API前、收到响应后、执行工具前打印出完整的数据结构。你会清晰地看到提示词最终的样子、模型返回的原始数据。简化与隔离当流程复杂出错时退回到最简单的可运行状态。例如如果带工具的智能体不工作就先测试不带工具的简单对话如果RAG失败就先测试固定的文本块能否被正确回答。逐步添加复杂度定位问题模块。使用Playground进行对比OpenAI和Anthropic的Web控制台Playground是绝佳的调试工具。将你在代码中构建的提示词复制到Playground里手动运行对比结果。这能帮你快速判断问题是出在提示词本身还是出在你的代码逻辑上。关注Token使用每次响应都检查usage字段。这能帮你发现提示词是否意外膨胀也是成本优化的依据。一个常见的优化是在长对话中将遥远的对话历史进行摘要而不是全部发送。走完这十步你获得的将不仅仅是十个可以运行的脚本。你将建立起一套关于AI应用如何工作的、坚不可摧的认知框架。当你在工作中再次听到“智能体”、“记忆”、“RAG”这些词时你的大脑里浮现的不再是模糊的概念而是一行行清晰的Python代码和数据结构。这种透过现象看本质的能力才是你在快速变化的AI时代最宝贵的资产。现在打开终端从git clone开始你的旅程吧每一步的代码都值得你亲手敲一遍并尝试去破坏它、修改它直到你真正理解它为什么这样工作。