2026年第 3 篇：大模型 API 调用实战（第一个 AI 应用）

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

注册/登录豆包平台：打开豆包官方API平台（https://www.doubao.com/apidoc/），使用字节跳动账号（抖音、今日头条账号均可）登录，没有账号的话，注册一个即可（全程免费，无需实名认证）。
进入API密钥管理页面：登录后，点击页面右上角的“个人中心”，在下拉菜单中选择“API密钥管理”，进入密钥管理界面。
创建API Key：在密钥管理界面，点击“创建API Key”，输入密钥名称（可自定义，如“我的第一个AI应用”），选择密钥权限（默认即可，无需修改），点击“确认创建”。
保存API Key：创建成功后，会显示你的API Key（一串由字母和数字组成的字符串，如“sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”），务必复制保存好——这个密钥只会显示一次，刷新页面后就无法再次查看，丢失后需要重新创建。
关键注意事项（重中之重）

API Key属于个人隐私，绝对不能泄露给他人（避免被他人盗用，产生不必要的费用），不要直接写在公开的代码、博客、社交平台上。
豆包新用户有免费调用额度，足够我们完成本次实战和后续的练习，无需担心费用问题；如果免费额度用完，可以在平台上购买套餐，价格亲民，适合新手。
如果API Key不慎泄露，立即在密钥管理界面点击“禁用”或“删除”，然后重新创建新的API Key，避免造成损失。
（二）安装必备依赖库：Python调用API的“工具包”
在第二篇Python入门中，我们已经学习了requests、json、dotenv这3个核心库，它们也是大模型API调用的必备工具——requests用于发送HTTP请求，json用于处理API返回的JSON数据，dotenv用于安全管理API Key（避免直接写在代码里）。
如果还没有安装这些库，打开VS Code的虚拟环境终端，输入以下命令，一次性安装完成（指定版本号，避免版本兼容问题）：

pip install requests==2.31.0

pip install python-dotenv==1.0.0

确定API地址（URL）：大模型服务器的“地址”，我们的请求需要发送到这个地址，豆包对话生成API的官方地址为：https://api.doubao-ai.com/v1/chat/completions ，这个地址可以在豆包API官方文档中查询到。
构造请求头（Headers）：用于向大模型服务器证明你的身份，核心是携带API Key，格式为 Authorization: Bearer 你的API Key ，同时需要指定请求数据格式为JSON（Content-Type: application/json），这是大模型API的通用要求。
构造请求参数（Body）：告诉大模型“要做什么”，比如你要问的问题、使用的模型、输出的长度等，参数格式为JSON，核心参数包括模型名称、对话消息列表等。
发送请求并解析结果：用requests库发送POST请求（几乎所有大模型API都用POST方式），接收大模型返回的JSON格式结果，解析出我们需要的回答内容。
简单来说，这4步就像“寄快递”：API地址是“收件地址”，请求头是“寄件人身份证”，请求参数是“快递内容”，发送请求是“寄出快递”，解析结果是“收到快递并打开查看”。理解这个类比，就能轻松记住API调用的核心逻辑。

load_dotenv()

api_key = os.getenv(“DOUBAO_API_KEY”)

api_url = “https://api.doubao-ai.com/v1/chat/completions”

# 第六步：解析返回结果（JSON格式转换为Python字典） response_dict = response.json() # 将API返回的JSON字符串转换为字典 # 提取大模型的回答内容：根据API返回的结构，逐层提取 # 豆包API返回结果的结构：response_dict → "choices"（列表）→ 第一个元素 → "message"（字典）→ "content"（回答内容） answer = response_dict["choices"][0]["message"]["content"] # 打印结果，查看效果 print("用户问题：", params["messages"][1]["content"]) print("AI回答：", answer)

创建.env文件：在你的Python项目文件夹中，新建一个名为“.env”的文件（注意前面有个小数点），打开文件后，写入内容：DOUBAO_API_KEY=你的API Key（将“你的API Key”替换成你之前获取的豆包API Key，等号前后不要有空格）。
复制代码：将上面的代码复制到VS Code的Python文件中（如“api_test.py”），确保虚拟环境已激活。
运行代码：点击VS Code右上角的“运行”按钮，查看底部终端的输出结果。
正常运行的输出结果示例：
用户问题：什么是大模型API调用？用简单的话解释一下。
AI回答：大模型API调用，就是用代码向大模型服务器发送请求，告诉它你想做什么（比如提问、生成内容），服务器处理后，再把结果返回给你。就像你给AI发消息，它回复你一样，只是用代码来实现这个过程，不用手动在APP里输入。
常见调试问题解决（新手高频踩坑）

问题1：运行代码后，提示“API调用失败，错误信息：‘DOUBAO_API_KEY’ not found”？
解决方法：检查.env文件是否创建正确，文件名是否为“.env”（不要少了小数点）；检查.env文件中是否正确写入“DOUBAO_API_KEY=你的API Key”，等号前后不要有空格；重启VS Code，重新加载环境变量。
问题2：提示“401 Unauthorized”（认证失败）？
解决方法：API Key错误或请求头格式错误。检查API Key是否正确（复制时不要多复制空格）；检查请求头中“Authorization”的格式是否正确，必须是“Bearer + 空格 + API Key”，缺一不可，这是最常见的认证失败原因。
问题3：提示“400 Bad Request”（请求参数错误）？
解决方法：检查请求参数的格式是否正确，比如messages是否是列表，每个元素是否是包含“role”和“content”的字典；检查model名称是否正确（必须是“doubao-pro-v1”，不能写错）；检查JSON格式是否有语法错误（如逗号遗漏、引号不匹配）。
问题4：提示“ConnectionError”（网络错误）？
解决方法：检查网络是否正常；豆包API不需要科学上网，若使用了代理，暂时关闭代理；检查API地址是否正确，不要写错字符。
（三）请求参数详解：新手必懂，灵活调整
在上面的代码中，请求参数（params）是核心，不同的参数设置会影响大模型的回答效果，新手需要掌握以下核心参数的含义，根据自己的需求灵活调整：

model（必选）：模型名称，豆包提供多种模型，新手优先使用“doubao-pro-v1”（专业版，功能强大、响应快，支持中文优化）；如果需要更轻量化的模型，可使用“doubao-lite-32k”（轻量版，速度更快，适合简单场景），具体模型列表可参考豆包API官方文档。
messages（必选）：对话消息列表，是API调用的核心，用于传递用户问题、历史对话和系统指令。每个元素是一个字典，包含两个键：

role：角色，可选值为“system”（系统）、“user”（用户）、“assistant”（大模型）；
content：对应角色的内容，system用于设定大模型的身份和回答风格，user是用户的问题，assistant是大模型的历史回答（多轮对话时需要）。

temperature（可选，默认0.7）：随机性参数，取值范围0-2。

取值越小（如0.1-0.3）：回答越严谨、固定，适合需要准确答案的场景（如知识问答、代码生成）；
取值越大（如0.8-1.5）：回答越灵活、有创意，适合需要生成多样化内容的场景（如文案创作、故事生成）。

max_tokens（可选，默认1000）：最大输出长度，单位是“token”（可理解为“字符片段”，1个中文字约等于2个token）。新手设置200-500即可，避免回答过长导致占用过多调用额度，同时也能控制回答的简洁度。
top_p（可选，默认0.7）：采样参数，与temperature配合使用，控制回答的多样性，取值范围0-1。一般不需要修改，保持默认值即可，若想让回答更集中，可适当降低top_p（如0.5）。
新手建议：先保持参数默认，熟悉API调用流程后，再逐步调整temperature和max_tokens，观察不同参数对回答效果的影响，找到适合自己场景的参数设置。

第一轮对话：messages = [{“role”: “user”, “content”: “什么是大模型？”}] → 大模型回答后，将这个回答加入messages；
第二轮对话：messages = [{“role”: “user”, “content”: “什么是大模型？”}, {“role”: “assistant”, “content”: “大模型是…”}，{“role”: “user”, “content”: “它有什么用途？”}] → 大模型根据历史对话，回答“大模型的用途是…”。
简单来说，就是“每次对话都带上之前的聊天记录”，让大模型“记住”你们之前聊过什么，这样就能实现连贯的多轮对话。
（二）多轮对话代码实现（可直接运行）
我们将编写一个可交互的多轮对话脚本，实现“用户输入问题→AI回答→继续输入问题→AI连贯回答”的功能，直到用户输入“退出”，结束对话。代码中加入了历史对话管理、用户交互、异常处理，完全贴合实际应用场景。

# 2. 判断用户是否退出 if user_input.strip() == "退出": print("AI助手：再见啦！有问题随时来找我哦～") break # 3. 将用户输入加入历史对话列表 history_messages.append({"role": "user", "content": user_input}) # 4. 调用API，获取AI回答 ai_answer = call_doubao_api(history_messages) # 5. 处理AI回答，加入历史对话列表 if ai_answer: print(f"AI助手：{ai_answer}") # 将AI回答加入历史对话列表，用于下一轮对话 history_messages.append({"role": "assistant", "content": ai_answer}) else: print("AI助手：抱歉，我暂时无法回答你的问题，请稍后再试～") # 移除本次用户输入（避免影响下一轮对话） history_messages.pop() print("=" * 50) # 分隔线，便于阅读

限制历史对话长度：如果对话次数过多，history_messages列表会越来越长，导致API调用速度变慢、占用更多token（消耗调用额度）。新手可以设置一个最大对话次数（如10次），超过次数后，删除最早的对话记录。
添加输入验证：比如判断用户输入是否为空，如果用户输入空格或空内容，提示用户“请输入有效的问题”，避免无效API调用。
优化回答格式：比如让AI回答时，开头加上“您好！”“好的～”等语气词，让对话更亲切，可修改system角色的content参数实现。
四、综合实战：开发第一个完整AI应用（智能对话助手）
经过基础调用和多轮对话的实战，我们已经掌握了API调用的核心技能。现在，我们将整合前面的知识，开发一个完整的AI应用——可交互、带功能菜单、支持多轮对话、能保存对话记录的智能对话助手，实现“从代码片段到完整应用”的跨越。
这个完整应用将包含以下功能：
功能菜单：显示“对话模式”“保存对话记录”“退出应用”三个选项，用户可选择功能；
多轮对话：支持连贯的多轮对话，AI能记住历史对话；
对话记录保存：将用户和AI的对话记录保存到本地TXT文件，便于后续查看；
完善的异常处理：处理API调用失败、用户输入无效、文件保存失败等常见问题；
友好的交互界面：添加菜单提示、分隔线、加载提示，提升用户体验。
（一）完整应用代码实现（可直接运行）

解析API返回的具体错误信息，更易理解

根据错误码给出针对性建议

打开文件，追加写入，编码为utf-8避免中文乱码

写入当前时间

写入对话记录

判断用户是否返回主菜单

验证用户输入是否有效

将用户输入加入历史对话

调用API获取回答

处理回答

while True:

try: # 接收用户选择 choice = input("请输入功能编号（1/2/3）：") # 处理用户选择 if choice == "1": dialog_mode() # 进入对话模式 elif choice == "2": # 保存对话记录（至少有一次有效对话才保存） if len(history_messages) > 1: # 排除system角色，至少有一次用户和AI对话 save_dialog_history(history_messages) else: print("

暂无对话记录可保存，请先进入对话模式进行对话～“)

 elif choice == "3": print("

感谢使用 AI 智能对话助手！再见啦～”)

 break else: print("

输入错误！请输入正确的功能编号（1/2/3）。“)

 print("=" * 60) except Exception as e: print(f"

程序运行异常：{str(e)}”)

 print("请重新输入功能编号～") print("=" * 60)

if name == “main”:
main()
（二）应用运行与功能测试
运行步骤：

确保.env文件已创建，且正确填写了API Key；
将上面的代码复制到VS Code的Python文件中（如“ai_assistant.py”）；
激活虚拟环境，运行代码，按照菜单提示操作。
功能测试要点：
测试对话模式：输入“1”进入对话模式，连续提问多个相关问题，检查AI是否能记住历史对话，给出连贯回答；输入“退出对话”，检查是否能返回主菜单。
测试保存对话记录：进行几次对话后，输入“2”，检查是否能成功保存对话记录，打开项目文件夹中的“dialog_history.txt”文件，查看对话记录是否完整。
测试异常处理：故意输入错误的API Key，运行应用，检查是否能给出明确的错误提示和解决建议；输入无效的功能编号（如“4”），检查是否能提示输入错误。
测试退出功能：输入“3”，检查应用是否能正常退出。
（三）应用优化方向（新手可尝试）
这个应用已经是一个完整的智能对话助手，但还有很多可以优化的地方，新手可以尝试以下优化方向，提升应用的实用性和体验：

添加角色切换功能：比如让用户选择“AI助手”“文案专家”“代码助手”等不同角色，修改system参数，实现不同场景的回答。
优化对话记录保存：比如让用户自定义保存文件名和保存路径，而不是固定为“dialog_history.txt”。
添加输入长度限制：比如限制用户输入的问题长度不超过500字，避免输入过长导致API调用失败。
添加多模型支持：比如同时支持豆包、文心一言等多个大模型，让用户选择使用哪个模型进行对话。

错误原因：API Key错误、API Key过期、请求头格式错误、API Key泄露后被禁用。
解决方法：

检查API Key是否正确，复制时不要多复制空格，确保和豆包平台上的一致；
检查API Key是否过期，若过期，在豆包平台重新创建API Key；
检查请求头中“Authorization”的格式，必须是“Bearer + 空格 + API Key”，缺一不可；
若API Key泄露，立即禁用并重新创建，避免被他人盗用。
（二）400 Bad Request（请求参数错误）
第二常见的报错，核心原因是请求参数格式错误或缺失必填参数。

错误原因：model名称错误、messages格式错误（不是列表或字典）、缺失role或content字段、JSON格式有语法错误（如逗号遗漏、引号不匹配）。
解决方法：

检查model名称是否正确，豆包新手请使用“doubao-pro-v1”，不要写错；
检查messages参数，确保是列表，每个元素是包含“role”和“content”的字典；
检查JSON格式，可使用在线JSON校验工具（如JSON.cn），校验请求参数的格式是否正确；
确保所有必填参数（model、messages）都已包含，没有遗漏。
（三）429 Too Many Requests（请求频率超限）
核心原因是短时间内发送的API请求过多，触发了大模型平台的限流机制，这是平台为了保护服务器稳定性设置的限制。

错误原因：短时间内多次调用API、调用频率超过平台限制（豆包免费用户有一定的调用频率限制）。
解决方法：

减少调用频率，在两次调用之间添加延迟（如用time.sleep(1)，每次调用间隔1秒）；
若需要高频调用，可在豆包平台购买更高额度的套餐，提升调用频率限制；
实现退避重试机制，遇到429错误时，等待一段时间后重新调用。
（四）500 Internal Server Error（服务端错误）
核心原因是大模型服务器出现异常，不是用户的问题。

错误原因：大模型服务器维护、服务器负载过高、临时故障。
解决方法：

稍等片刻（1-5分钟），重新调用API；
查看豆包API官方公告，确认是否有服务器维护通知；
若多次调用仍失败，可联系豆包官方技术支持。
（五）ConnectionError（网络错误）
核心原因是网络连接失败，无法连接到大模型服务器。

错误原因：网络断开、使用代理导致无法连接、API地址错误、防火墙拦截。
解决方法：

检查网络是否正常，确保能正常访问互联网；
若使用了代理，暂时关闭代理，豆包API不需要科学上网；
检查API地址是否正确，确保是“https://api.doubao-ai.com/v1/chat/completions”；;
检查防火墙是否拦截了请求，暂时关闭防火墙重试。
（六）max_tokens exceeds limit（输出长度超限）
核心原因是设置的max_tokens超过了模型的最大支持长度，或历史对话过长，导致总token数超过限制。

错误原因：max_tokens设置过大（如超过1000）、历史对话记录过长，总token数超过模型的最大支持额度。
解决方法：

降低max_tokens的值，新手设置200-500即可；
清理历史对话记录，删除最早的对话，减少总token数；
选择支持更长上下文的模型（如豆包的“doubao-pro-32k”，支持32k上下文）。

本文作为大模型API调用的实战篇，核心是帮你从“理论”落地到“实操”，通过一步步的实战，掌握API调用的完整流程，成功开发出第一个AI应用（智能对话助手）。总结一下本次实战的核心要点：

API调用的核心逻辑：4步走（确定API地址→构造请求头→构造请求参数→发送请求并解析结果），本质是“用代码给大模型发消息、收消息”。
关键准备：API Key是“通行证”，务必安全管理，不要泄露；requests、dotenv是必备工具，必须熟练使用。
多轮对话的核心：将历史对话记录加入messages列表，让大模型“记住”上下文，实现连贯对话。
实战重点：多动手、多调试，遇到报错不要慌，对照“常见报错汇总”，快速定位问题、解决问题——报错是新手成长最快的方式。
完整应用的逻辑：整合基础功能，添加交互菜单、异常处理、数据保存，让代码从“可运行”变成“可用”，贴合实际应用场景。
到这里，你已经完成了大模型应用开发的核心实战——能独立调用大模型API，开发出简单的AI应用，这已经超越了80%的新手。下一步，我们将学习更实用的技能：Prompt工程（让大模型的回答更精准、更贴合需求），以及RAG技术（搭建文档问答系统，让AI能基于你的本地文档回答问题）。
提示：在进入下一步学习前，建议多练习本次实战的代码，尝试修改参数、优化应用，熟悉API调用的细节，把基础打扎实——只有熟练掌握API调用，才能更好地学习后续的进阶内容。