搜「AI应用开发入门教程」的人，多数不是缺理论，而是环境看着装好了、请求却发不出去。判断顺序建议是：先确认版本、权限、入口位置这三件事，再用一条最小请求把链路跑通，最后才去考虑提示词质量、批量处理和效果评估。跳过前面直接抄示例代码，通常会在认证或地址这一步耗掉大半时间，还容易误以为是模型的问题。
适用场景：第一次把模型接进自己的项目，做 demo 或内部小工具。操作动作：命令行确认运行时与 SDK 版本，控制台核对 Key 状态与可用额度，从接入文档页原样复制 base_url，再跑一条带超时和重试的最小请求。验证方式：终端能打印出正常回答，并且打印出 usage（token 用量）字段。风险边界：模型名、限速、额度、计价都会变，具体取值以控制台与接入文档当前显示为准，不要照抄二手教程里的旧值。
AI应用开发入门之前先确认这三件事
这三件事缺一件，后面的代码基本白调。每一项都能在本地命令或控制台页面里看到，不靠猜。
- 版本：运行时和 SDK 版本对不上，常见表现是导入报错或参数不被识别。看的位置是命令行：
python -V看运行时，pip show openai看已装 SDK 版本（包名以接入文档为准），pip index versions openai看能装到哪些版本。建议把虚拟环境建在项目目录下，避免和系统环境混用。 - 权限：Key 是否有效、账号有没有可用额度、目标模型是否在可用范围内。看的位置是控制台的「API Keys」「用量/配额」「模型列表」这类面板项，对应字段通常是 Key 状态、剩余额度、模型名称。新建的 Key 有时需要短暂等待生效，建议建完后再发一次请求确认。
- 入口位置：base_url 或 endpoint 必须从控制台「快速开始 / 接入示例」页面里复制，不要从博客或记忆里抄。不同 SDK 里字段名可能是 base_url、endpoint 或 api_base，需要结合接入文档确认，写错一个斜杠就会变成 404。
AI应用开发入门：最短可用路径
四步，每步只做一件事。做完一步再进下一步，出错时才知道是哪一层的问题。
第 1 步：建环境并装依赖。
python -m venv .venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
pip install -U openai python-dotenv pyyaml
python -c "import openai; print(openai.__version__)"做完该看到：终端打印出一个版本号，没有 ImportError。
第 2 步：把 Key 和地址放进 .env，不写进代码。
API_KEY=sk-xxxxxxxx
BASE_URL=https://控制台接入页给出的域名/v1
MODEL=控制台模型列表里显示的名称再执行 chmod 600 .env，把 .env 写进 .gitignore。做完该看到：ls -l .env 的权限位是 -rw-------。
第 3 步：跑一条最小请求。
import os
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
client = OpenAI(
api_key=os.environ["API_KEY"],
base_url=os.environ["BASE_URL"],
timeout=20.0,
max_retries=2,
)
resp = client.chat.completions.create(
model=os.environ["MODEL"],
messages=[{"role": "user", "content": "用一句话说明 HTTP 404 是什么意思"}],
temperature=0.2,
)
print(resp.choices[0].message.content)
print(resp.usage)做完该看到：先打印一段中文回答，再打印出一个 usage 对象，里面带输入和输出的 token 数。
第 4 步：把异常打出来。在请求外面包一层 try/except，把 status_code 和错误内容一起打印。这一步不解决任何业务问题，但后面排查全靠它——没有错误原文，只能猜。
AI应用开发入门：一个真实场景的完整做法
场景具体化：内部客服工单分类。本地有一个 tickets.jsonl，约 300 条，每条字段是 id、text（工单正文，一般几十到两三百字），需要给每条打上「退款 / 物流 / 账号 / 其他」四类之一，结果落到 out.jsonl。这种情况不需要并发，串行跑、能断点续跑比追求速度重要。
配置放在两个地方：config.yaml（提示词模板和类别列表，方便改），.env（Key、BASE_URL、MODEL，从控制台页面复制）。模型名称以控制台「模型列表」页面显示的为准。
# config.yaml
labels: [退款, 物流, 账号, 其他]
prompt: "工单内容：{text}\n只能从这些类别里选一个：{labels}"# classify.py
import json, os, yaml
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
cfg = yaml.safe_load(open("config.yaml", encoding="utf-8"))
client = OpenAI(api_key=os.environ["API_KEY"], base_url=os.environ["BASE_URL"],
timeout=30.0, max_retries=2)
done = set()
if os.path.exists("out.jsonl"):
done = {json.loads(l)["id"] for l in open("out.jsonl", encoding="utf-8")}
with open("out.jsonl", "a", encoding="utf-8") as fout, \
open("tickets.jsonl", encoding="utf-8") as fin:
for line in fin:
row = json.loads(line)
if row["id"] in done:
continue
prompt = cfg["prompt"].replace("{text}", row["text"]).replace("{labels}", "/".join(cfg["labels"]))
resp = client.chat.completions.create(
model=os.environ["MODEL"], temperature=0,
messages=[{"role": "system", "content": "只输出一个类别词，不要解释"},
{"role": "user", "content": prompt}],
)
label = resp.choices[0].message.content.strip()
if label not in cfg["labels"]:
label = "待人工"
fout.write(json.dumps({"id": row["id"], "label": label}, ensure_ascii=False) + "\n")
fout.flush()先只跑前 10 条：把输入文件临时截出 10 行，确认输出格式对，再跑全量。跑完后抽 20 条人工核对，重点是模型给出类别列表之外的词、被兜底成「待人工」的那些。这类样本通常说明提示词里的类别约束不够明确，或者这条工单本身跨类。断点续跑靠 out.jsonl 里已有的 id 判断，中途中断重跑不会重复计费。
AI应用开发入门：跑不通先查这三处
第一处：认证与权限，表现为 401 / 403。错误提示通常形如 Error code: 401 - Incorrect API key provided 或 invalid_api_key；403 常见的是 permission denied 或提示模型未对当前账号开放。检查位置：.env 里的 Key 有没有多余空格、引号或换行；控制台「API Keys」页面该 Key 是否仍在列表中、状态是否正常；账号「用量/配额」页面额度是否已经用完。
第二处：地址和模型名，表现为 404。提示通常形如 Error code: 404 - model not found，或者干脆返回一段 Not Found 的 HTML。前者多半是 MODEL 名字和模型列表页显示的不一致，注意大小写和日期后缀；后者通常是 base_url 写错了，比如多写或漏写了 /v1，或者域名拼错。检查位置：把控制台接入示例页给出的地址原样复制过来逐字符比对，不要自己拼。
第三处：限流与超时，表现为 429 或请求超时。提示形如 Error code: 429 - rate limit reached，或客户端抛 Request timed out。检查位置：控制台「用量/配额」页面的限速说明；代码里 timeout 设了多少（20 到 30 秒对单条短文本通常够用）；批量脚本里是否一次开了太多并行——建议先降到串行，逐条跑通再考虑提高。需要提醒的是，重试只能缓解偶发限流，额度耗尽时重试没有意义；超时也可以先用更短的输入验证链路通不通，再换回真实数据。