前言

近期基于 Python + OpenAI SDK 尝试搭建简易 AI Agent，目标实现多轮上下文记忆、持续对话交互。过程中先后测试了硅基流动、DeepSeek、阿里云通义千问等多款国内大模型服务，接连遇到密钥读取、模型禁用、接口兼容、超时、语法错误等各类问题。

本文整理实操过程中遇到的典型问题、原因分析与对应解决方案，同时附上最终稳定可用的完整代码，帮刚入门的开发者少走弯路。

一、项目基础信息

技术栈

• 编程语言：Python
• 调用 SDK：openai 官方 SDK
• 最终服务：阿里云百炼（通义千问 兼容接口）
• 选用模型：qwen3-8b

实现功能

1. 多轮对话，上下文记忆
2. 支持手动清空对话记忆、退出程序
3. 国内直连，无需特殊网络环境
4. 异常捕获，友好提示错误信息

二、实操踩坑 & 解决方案（按遇到顺序整理）

坑 1：API Key 读取失败，客户端初始化报错

报错信息

openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable

问题原因

初期使用 python-dotenv 读取 .env 环境变量，存在文件路径不对、加载时机错误、变量名不匹配等问题，导致密钥无法正常读取。

解决方案

新手入门优先直接硬编码传入密钥，跳过环境变量读取流程，简化配置、规避路径与加载问题。后续项目复杂后，再改用环境变量管理密钥。

坑 2：硅基流动平台模型禁用 / 模型不存在

报错信息

Model disabled
Model does not exist

问题原因

1. 硅基流动平台会不定期下线、调整开源模型，很多教程中的旧模型名称已失效；
2. 平台内大部分开源模型不支持 Function Calling 工具调用，无法实现计算器、时间查询等扩展能力。

解决方案

放弃硅基流动，更换稳定性更强、模型长期在线的国内大模型平台。

坑 3：接口请求超时，程序卡住无响应

报错信息

Request timed out

问题原因

7B/14B 量级开源模型访问量高、服务器负载大，高峰期接口响应延迟极高，默认超时时间不足以完成请求。

解决方案

1. 初始化客户端时，手动延长 timeout 超时时间；
2. 更换企业级稳定模型，降低超时概率。

坑 4：DeepSeek 平台余额不足

报错信息

Insufficient Balance

问题原因

新用户免费额度有调用次数限制，额度耗尽后无法继续请求接口。

解决方案

长期学习优先选择免费额度充足、政策稳定的阿里云百炼平台，适合入门练习。

坑 5：通义千问接口参数不兼容

报错现象

调用接口直接返回参数非法，请求失败。

问题原因

通义千问新版模型默认开启思考模式 enable_thinking，原生 OpenAI SDK 未适配该参数，直接调用会报错。
解决方案
在请求参数中新增 extra_body={"enable_thinking": False}，手动关闭思考模式，完成接口兼容。
坑 6：代码语法问题，记忆功能异常
问题现象
输入 clear无法清空记忆；
变量名前后不一致，触发NameError。
问题原因
字符串方法书写错误：user_input.lower漏写括号，正确应为 user_input.lower()；
全局对话列表变量名前后不统一。

解决方案

统一全局变量命名，修正字符串方法语法，规范全局变量修改逻辑。

三、最终稳定方案选型

综合稳定性、免费额度、接口兼容性、模型可用性，最终确定组合：

• 接口地址：https://dashscope.aliyuncs.com/compatible-mode/v1
• 模型名称：qwen3-8b
• 核心优势：国内直连、长期稳定、免费额度充足、完美兼容 OpenAI SDK、支持工具调用扩展。

四、完整可运行代码

from openai import OpenAI

# 初始化通义千问兼容接口客户端
client = OpenAI(
    api_key="你的阿里云百炼API Key",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

# 全局对话列表：存储系统提示、用户提问、AI回答，实现上下文记忆
messages = [
    {"role": "system", "content": "你是一个乐于助人、简洁回答的助手"}
]

def run_agent():
    print("=" * 50)
    print("AI Agent 已启动（支持上下文记忆）")
    print("指令说明：exit/退出 结束程序 | clear 清空对话记忆")
    print("=" * 50)

    while True:
        user_input = input("\n你：")

        # 退出程序逻辑
        if user_input.lower() in ["exit", "退出"]:
            print("👋 程序已退出，再见！")
            break

        # 清空对话记忆逻辑
        if user_input.lower() == "clear":
            global messages
            messages = [{"role": "system", "content": "你是一个乐于助人、简洁回答的助手"}]
            print("🧹 对话记忆已清空！")
            continue

        # 将用户提问加入对话上下文
        messages.append({"role": "user", "content": user_input})

        try:
            # 调用大模型接口
            response = client.chat.completions.create(
                model="qwen3-8b",
                messages=messages,
                extra_body={"enable_thinking": False}
            )

            # 解析返回结果
            answer = response.choices[0].message.content
            print(f"\n🤖 Agent：{answer}")

            # 将AI回答加入上下文，实现记忆延续
            messages.append({"role": "assistant", "content": answer})

        except Exception as e:
            print(f"\n❌ 运行出错：{e}")

if __name__ == "__main__":
    run_agent()

五、代码使用说明

1. 安装依赖

pip install openai

2. 替换代码中 api_key为你自己的阿里云百炼 API Key；
3. 运行脚本 python agent.py；
4. 交互指令：正常聊天、clear清空记忆、exit退出程序。

六、学习总结与后续规划

本次从零搭建简易 AI Agent，最大的收获不只是完成代码编写，更是熟悉了大模型接口调用、多轮对话实现、线上服务排错的完整流程。

对于新手而言，AI Agent 入门难点往往不在于代码逻辑，而在于各平台接口差异、模型状态变动、参数兼容问题。经过多轮测试对比，阿里云通义千问是目前国内个人学习、练手的优选方案。

当前版本已实现基础多轮对话，后续计划继续迭代：

1. 增加工具调用能力（计算器、时间查询）；
2. 优化上下文，自动裁剪过长对话，避免 Token 超限；
3. 尝试接入 RAG 知识库，实现本地文档问答。