ai开发入门教程

你可能已经会写代码，但一到「把大模型接进自己的程序」就卡住：不知道先做哪一步、报错看不懂、成本心里没底、跑通一个 demo 之后又不知道该往哪走。这篇按真实上手顺序拆成几步，每步告诉你做什么、做到什么算过关、卡住了先查哪。数字类的东西一律指到站内对应页面去核对，避免你抄到过期的口径。

你可能已经会写代码，但一到「把大模型接进自己的程序」就卡住：不知道先做哪一步、报错看不懂、成本心里没底、跑通一个 demo 之后又不知道该往哪走。这篇按真实上手顺序拆成几步，每步告诉你做什么、做到什么算过关、卡住了先查哪。数字类的东西一律指到站内对应页面去核对，避免你抄到过期的口径。

先给个心理预期：AI 应用开发和普通后端开发最大的区别，不在语言和框架，而在「输入输出都是不确定的」。你调一个普通接口，参数对就返回固定结构；你调模型接口，同样的输入可能给出不一样的回复，还可能因为限速、超时、上下文过长而失败。所以入门阶段真正要练的，不是会不会写那一行调用代码，而是能不能把不确定的部分框住：先跑通，再加约束，最后才是优化。下面按这个逻辑走。

先分清：你要做的到底是哪种「AI 开发」

很多人上来就问「用什么框架」，其实问错了。先确认你要交付的东西是什么形态，路线自然就定了。三条路线的前置条件、学习成本和产出差别很大，选错了会白折腾好几周。

• 判断标准一：需求里有没有「必须联网拿实时数据」。有，就先走接口或 Agent 路线，本地模型本身不知道今天发生了什么。
• 判断标准二：有没有「数据不能出内网」。这是唯一能理直气壮选本地部署的理由，其他理由都要算算运维成本。
• 判断标准三：要不要「塞进已有后端」。要，那你的第一个目标不是做界面，而是把调用封装成一个内部函数。
• 不适用的情况：如果你只是想要一个能聊天的入口、不做任何集成，那属于工具选型问题，去 /tools 里挑现成的就行，别当成开发任务绕远路。

动手写代码之前，先把模型和入口定下来

别急着写代码，先把「用哪家、用哪档、走什么入口」定下来。这一步花二十分钟，能省掉后面反复换接口的返工。模型选型不是选最强，是选最匹配，你的任务类型决定了你看哪几个维度。

任务类型

对话、信息抽取、写代码、看图，是四类完全不同的能力，先确认你的核心场景属于哪类。

上下文长度

你要塞进去的资料有多长，超了就得切分，切分方案要在选型阶段就想好。

并发与限速

你的峰值请求量是多少，限速扛不住时是排队还是降级，这决定架构复杂度。

计费方式

按量还是订阅，直接影响你代码里要不要做用量控制。

同一家的不同档位差别很大。务实的做法是：先用门槛最低的小档位把整条流程跑通，等效果确实不够了再换。反过来，一上来就上最贵的那档，你连是自己的代码有问题还是模型选错都分不清。规格和计价口径这类会变的东西，去 /models 和 /official-api 对照当时的数字，别凭印象记。

Key、环境变量与第一次请求

第一步不是写业务逻辑，是让一次最小请求返回正常结果。这一步过关的标准很朴素：能拿到一段格式正确、内容合理的返回，就继续往下走，暂时不要调任何参数。调参是后面的事，越早调越乱。

1. 拿到 Key 并放进环境变量不要写死在代码里，也不要提交进版本库。原因和具体做法见 /guides/env-var-api-key-setup，照着配一次就行。
2. 写一个最小请求只发一条最简单的输入，不加系统提示词、不改温度、不设额外参数，先确认链路通。
3. 看返回结构重点不是内容好不好，而是字段结构你能不能正确解析，尤其是错误分支长什么样。
4. 故意造一次错把 Key 改错一位再发一次，看看你的代码会不会把错误吞掉。这一步能帮你提前发现兜底逻辑的漏洞。

报错先按状态码分类，再按 error code 文本细分。状态码看 /guides/api-errors，能快速判断是认证、限速还是服务端问题；文本含义看 /guides/api-error-code-lookup，同一个词在不同平台可能指不同东西，所以要拿原样复制的错误文本去比对，别自己转述。

一个能跑的最小应用骨架长什么样

跑通单次请求之后，把它包装成一个能重复调用的小应用。这里的关键是别急着做界面，先用命令行或一个单页把链路走完整。界面留到最后做的原因很实际：调试时你要能确定问题出在接口、逻辑还是渲染，混在一起排查成本翻倍。

• 输入收集：把用户输入整理成一个明确的结构，顺便做长度和空值检查。
• 请求封装：统一处理超时和重试，重试要设上限，别写成死循环。
• 输出渲染：把返回内容按你的场景格式化，注意处理流式返回拼装的情况。
• 错误兜底：每一种失败都要有用户能看懂的话，而不是把原始报错甩出去。
• 原始日志：把请求和返回原样记一份，出问题时这是唯一能复现的凭据。

这五块里，最容易被新手省掉的是日志和错误兜底，而这两块恰恰是你上线后最需要的。日志不用做得复杂，写到本地文件或者你现有的日志系统里就行，关键是要原样，不要只记你解析之后的字段。

第一批该调的参数只有几个

参数很多，但入门阶段真正值得动的就四个。顺序建议是：先设输出长度上限，再调温度，然后写系统提示词，最后配超时时间。其余参数等你确实遇到具体问题再说，看到文档里有什么就调什么，只会让问题更难定位。

关于输出稳定性，同一问题每次答案不一样，很多时候不是模型坏了。什么时候算正常、怎么让它更可复现，可以看 /guides/output-stability-reproducible。上下文越来越长会明显影响成本和延迟，治理思路见 /guides/context-window-management，这块别等到账单或用户投诉才想起来处理。

别等账单出来才发现用量失控

成本这块，入门阶段不需要精确预测，但一定要有感觉。最实用的估算方式是：先量出单次请求大概消耗多少输入和输出，乘以你预估的每天请求数，再留一倍冗余。注意输入和输出通常不是一个价，所以两侧都要算；具体单价和换算，去 /tools/token-price-calculator 和 /tools/model-cost-calculator 现查，别用别人文章里的旧数字。

估算只是心理准备，真正的防线是代码里的闸门。至少要加两个：单次请求上限和每日总量上限。前者防止一次异常输入把上下文撑爆，后者防止程序失控或者被刷。这两个闸门的作用不是省钱，而是让你在出问题时有个明确的停止点，不至于第二天早上才发现扣了一大笔。

跑不通时的固定排查顺序

新手最容易犯的错是到处乱改：一会儿换模型，一会儿改代码，一会儿重装依赖。给定一个固定顺序，按顺序排查，命中就停，这样效率最高，也能积累经验。

1. 一查 Key 是否生效用最小请求测试，确认认证这关过了，别把认证问题当成业务问题查。
2. 二查 base_url 是否写对写错地址是最隐蔽的坑，本地能跑不代表配置对，很多 SDK 有默认值会掩盖问题。
3. 三查模型名确认你用的名字在支持列表里，且入口和名字是配套的，别混用不同入口的命名。
4. 四查网络与超时前面都过了还失败，八成是出口网络或超时设置的问题，这种情况本地能跑线上会挂。

同样的报错在不同平台可能指不同东西，所以别用自己转述的描述去搜，要用原样复制的错误文本。另外，本地能跑、上线就挂，绝大多数是环境变量没带过去或者出口网络不通这两类问题，先查这两个，别去怀疑模型。

跑通之后往哪走

跑通一个能对话的应用之后，下一步取决于你想解决什么，不要盲目堆功能。每加一层都会带来新的成本和新的排错面，原则是：一层通了、稳了，再加下一层。想加什么功能，对照你的实际需求来选。

• 要记住历史对话 → 加会话存储，注意上下文会越来越长，成本和延迟都会涨。
• 要读你自己的资料 → 上检索增强，重点在切分策略和检索质量，不在模型本身。
• 要让模型自己调工具 → 上工具调用 / Agent，这时排查面会从「一次请求」变成「一条链路」。
• 要做成产品给他人用 → 回头补限速、配额、审计和错误上报。

路线上的取舍可以参考 /guides/llm-app-dev-beginner-path 和 /guides/ai-agent-learning-path，里面把从调接口到做 Agent 的层次拆得比较细。别一上来就奔着最复杂的形态去，先把最小闭环跑稳，后面的每一步都会轻松很多。

入门的标志不是你能写多复杂的调用，而是你能说清楚每一次失败的原因。