本章你将完成的事：

1. 学会安全、稳健地调用大模型 API（含错误处理）
2. 理解不同模型的差异，掌握"模型选型"的方法
3. 用 Streamlit 把 AI 能力封装成可演示的界面
4. 体验一个 Demo：AI+X 多模型对比工具

---

5.1　为什么是这三个关键

第 4 章我们走完了 Vibe Coding 的完整工作流：搭环境、写提示词、迭代调试、代码审查。但很多同学到这一步会遇到一个新问题——TRAE 生成的代码看起来都对，为什么跑起来总是出错？

复盘一下常见的报错：

• HTTP 401 Unauthorized：API Key 没配对
• KeyError: 'choices'：返回的 JSON 结构不对
• ConnectionError：网络不通
• 界面打开了，但点按钮没反应
• 同样的问题，换一个模型就跑通了

把这些报错归类一下，其实就三个根源：

1. API 调用没做对——Key、URL、请求体、超时、错误处理
2. 模型选错了——不同模型擅长的事情不一样，免费额度也不一样
3. 界面没搭好——AI 返回的结果没正确地呈现给用户

这三个关键，就是本章的主题。 掌握了它们，你做任何 AI+X 项目都能"跑起来"。

为了让你边学边练，本章配了一个综合 Demo：AI+X 多模型对比工具。它一次解决三个关键——安全调用 API、对比多个模型、用 Streamlit 展示结果。我们会一边讲原理，一边对照这个 Demo 讲实现。

---

5.2　第一个关键：API 调用——安全 + 错误处理

5.2.1　调用 API 的"四件套"

不管用哪个国内大模型（DeepSeek、Qwen、Kimi……），硅基流动的调用方式都是一样的，就是一次普通的 HTTP POST 请求。你只需要准备好"四件套"：

件	内容	说明
1	URL	https://api.siliconflow.cn/v1/chat/completions
2	Headers	Authorization: Bearer <你的Key> + Content-Type: application/json
3	Body	model、messages、temperature、max_tokens 等字段
4	Timeout	网络请求超时时间（建议 60-90 秒）

其中 Body 的核心结构是 messages，它是一个对话历史列表：

messages = [
    {"role": "system", "content": "你是一位专业的文本分析助手。"},  # 系统提示
    {"role": "user", "content": "分析以下古诗的风格：..."}           # 用户输入
]

• role: system：告诉模型它扮演什么角色
• role: user：用户输入的问题或任务

这套结构来自 OpenAI 的 Chat Completions 协议，硅基流动、智谱、阿里云百炼、Kimi 都遵循这套协议。学会这一套，国内所有大模型你都会调用。

5.2.2　安全第一：API Key 不要硬编码

最容易踩的坑，就是把 API Key 直接写在代码里：

# ❌ 错误写法：Key 硬编码
API_KEY = "sk-yfmgvsyjrkfmbebzazktoedxaspbfhomjliujbwvufopdhmu"

这样做有三个风险：

1. 泄露风险：把代码分享给别人、传到 GitHub，Key 就泄露了
2. 管理麻烦：换 Key 要改代码，多个文件要改多处
3. 教学场景不友好：教材里出现真实 Key，读者复制就会用到你的额度

正确做法：用 .env 文件 + python-dotenv 库。

第一步，在项目根目录创建 .env 文件（注意文件名就是 .env，没有前缀）：

SILICONFLOW_API_KEY=sk-你的真实Key

第二步，在代码里读取：

import os
from dotenv import load_dotenv

load_dotenv()                                    # 加载 .env 文件
API_KEY = os.getenv("SILICONFLOW_API_KEY")       # 从环境变量读取

第三步，把 .env 加到 .gitignore，避免上传到 Git 仓库：

# .gitignore
.env

💡 教材里的 Key 怎么处理：本书所有示例代码中出现的 API Key 都用 your_siliconflow_api_key 这种占位符代替，不会出现真实 Key。你拿到代码后，把 .env.example 复制为 .env，填入你自己的 Key 即可。

5.2.3　错误处理：让代码"摔不坏"

API 调用最容易出错，原因有很多：

错误类型	原因	典型报错
网络错误	网络断开、DNS 解析失败	ConnectionError
超时错误	模型推理太久	Timeout
认证错误	API Key 错误	HTTP 401
限流错误	请求太频繁	HTTP 429
参数错误	模型名拼错、消息格式错	HTTP 400
服务错误	硅基流动服务异常	HTTP 500

如果不做错误处理，任何一个错误都会让程序崩溃。好的代码必须"摔不坏"——出错也要给用户一个友好提示。

Demo 里的做法是用 try-except 包裹整个调用过程：

def call_model(prompt: str, model: str, system_prompt: str = "你是一位专业的文本分析助手。") -> dict:
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": model,
        "messages": [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": prompt}
        ],
        "temperature": 0.7,
        "max_tokens": 1500,
    }
    start_time = time.time()
    response = requests.post(API_URL, json=payload, headers=headers, timeout=90)
    elapsed = time.time() - start_time
    response.raise_for_status()        # HTTP 错误（401、429 等）会在这里抛出
    result = response.json()
    content = result["choices"][0]["message"]["content"]
    tokens = result.get("usage", {}).get("total_tokens", "未知")
    return {"content": content, "elapsed": elapsed, "tokens": tokens}

调用方再包一层异常处理，针对不同错误给出不同提示：

try:
    result = call_model(task_input, model_id, system_prompt)
except requests.exceptions.HTTPError as e:
    results[model_id] = {"error": f"API 错误：{e}"}
except requests.exceptions.RequestException as e:
    results[model_id] = {"error": f"网络错误：{e}"}
except Exception as e:
    results[model_id] = {"error": f"未知错误：{e}"}

这样即使某个模型调用失败，程序也不会崩溃，只会显示具体错误，其他模型的对比还能继续。

⚠️ 常见坑：超时设置：默认 requests.post 没有超时，模型推理慢时会一直等。一定要加 timeout=90（秒），避免界面卡死。

5.2.4　API 调用检查清单

每次写 API 调用代码，对照这份清单：

检查项	怎么检查
Key 不硬编码	搜索代码里有没有 sk- 开头的字符串
Key 从 .env 读	os.getenv("SILICONFLOW_API_KEY")
URL 正确	必须是 https://api.siliconflow.cn/v1/chat/completions
Headers 完整	Authorization + Content-Type
Body 结构对	model + messages 必须有
设置超时	timeout=90
有错误处理	try-except 包裹 requests.post
区分错误类型	HTTP 错误、网络错误、未知错误分别处理

---

5.3　第二个关键：模型选择——对比 + 选优

5.3.1　国内免费模型怎么选

硅基流动上有几十个模型，新手容易挑花眼。本书推荐三个免费、稳定、有代表性的模型：

模型	模型 ID	特点	适用场景
Qwen2.5-7B	Qwen/Qwen2.5-7B-Instruct	速度快、回答简洁	入门项目、快速演示
Qwen3-8B	Qwen/Qwen3-8B	推理强、回答细致	分析类任务、需要详细输出
DeepSeek-R1	deepseek-ai/DeepSeek-R1-0528-Qwen3-8B	深度思考、推理链	复杂分析、需要多步推理

新手误区：不是模型越大越好。7B 模型虽然参数少，但回答简洁快速，做演示足够了；R1 推理深但慢，做实时交互不合适。

5.3.2　模型选型的三个维度

选模型不能只看"好不好用"，要从三个维度综合考量：

维度一：质量

回答是否准确、是否有结构、是否覆盖要点。比如分析古诗风格，要看模型有没有分析用词、句式、情感等多个维度。

维度二：速度

响应时间多少秒？做实时交互（聊天机器人）的话，超过 10 秒用户就受不了；做后台分析（一次跑批）的话，1 分钟也能接受。

维度三：成本

消耗多少 Token？免费额度有限，Token 越少越省钱。同样一个任务，A 模型消耗 300 Token，B 模型消耗 1500 Token，长期用差别很大。

💡 什么是 Token：Token 是大模型计费的最小单位。中文大约 1 个字 = 1-2 个 Token，英文大约 1 个单词 = 1 个 Token。usage.total_tokens 字段会返回本次调用消耗的总 Token 数（输入 + 输出）。

5.3.3　为什么需要"对比工具"

光看文档介绍，很难判断哪个模型适合你的项目。最好的办法是拿你自己的真实任务，同时调用多个模型，看结果对比。

这就是本章 Demo 的设计初衷——AI+X 多模型对比工具。你输入一个分析任务，它同时调用三个模型，把回答、耗时、Token 消耗并排展示，让你一眼看出差异。

看一个真实的对比结果（输入：“分析以下古诗的风格特点：《静夜思》床前明月光，疑是地上霜。举头望明月，低头思故乡。”）：

模型	耗时	Token 消耗	状态
Qwen2.5-7B	9.6s	339	✅ 成功
Qwen3-8B	—	0	❌ 网络超时
DeepSeek-R1	42.0s	1,141	✅ 成功

可以看出：

• Qwen2.5-7B 最快，但回答相对简短
• DeepSeek-R1 最慢但思考最深，Token 消耗也最大
• Qwen3-8B 偶尔会因为网络波动超时——这正是 5.2 节错误处理的价值

这种"看结果说话"的对比，比看任何文档介绍都直观。

5.3.4　模型选型决策表

做完对比后，怎么决策？参考这张表：

你的需求	推荐模型	理由
快速演示、界面交互	Qwen2.5-7B	速度快，用户体验好
文本分析、需要详细输出	Qwen3-8B	回答细致，结构清晰
复杂推理、多步骤任务	DeepSeek-R1	推理深，准确率高
不确定选哪个	都用对比工具跑一遍	用数据说话

💡 教学建议：本书实战篇的案例默认用 Qwen2.5-7B，因为它速度快、免费额度足、回答质量也够用。如果你做的是分析类项目（如文本风格分析），可以试试 Qwen3-8B；如果项目需要复杂推理（如多步骤决策），可以试 DeepSeek-R1。

---

5.4　第三个关键：界面部署——Streamlit 快速原型

5.4.1　为什么是 Streamlit

AI+X 项目做完 API 调用，只完成了一半——用户没法用。总不能让别人打开命令行、写 Python 代码来用你的工具。

需要一个能快速做界面的工具。常见选择有三个：

框架	上手难度	适合场景	是否需要前端知识
Streamlit	⭐ 最简单	数据应用、AI Demo	不需要
Gradio	⭐⭐ 简单	模型演示、表单类	不需要
Flask + 前端	⭐⭐⭐⭐ 难	复杂 Web 应用	需要

本书所有 Demo 都用 Streamlit，原因有三：

1. 零 HTML/CSS/JS 基础：纯 Python 写界面
2. AI 友好：内置按钮、文本框、表格、图表、文件上传等组件，组合即可
3. 免费开源：pip install streamlit 就能用，无需注册

5.4.2　Streamlit 的"四件套"

写一个 Streamlit 应用，只需要四类代码：

import streamlit as st

# 1. 页面配置
st.set_page_config(page_title="我的应用", page_icon="⚡", layout="wide")

# 2. 标题与说明
st.title("⚡ 我的应用")
st.caption("一句话说明这个应用做什么")

# 3. 输入组件
user_input = st.text_area("输入你的文本", height=100)
if st.button("开始", type="primary"):
    # 4. 输出结果
    st.markdown("处理结果：")
    st.markdown(user_input)

把这四件套组合起来，就能做出 90% 的 AI 应用界面。本章 Demo 用的就是这套结构。

5.4.3　Demo 界面拆解

我们对照 Demo 代码看 Streamlit 怎么用。

第一部分：页面配置与标题

st.set_page_config(page_title="AI+X 多模型对比工具", page_icon="⚡", layout="wide")

st.title("⚡ AI+X 多模型对比工具")
st.caption("同一个问题，不同模型回答有什么区别？一键对比，帮你选出最适合的模型")

• set_page_config：设置浏览器标签页标题、图标、布局（wide 宽屏，centered 居中）
• title：大标题
• caption：副标题，灰色小字

第二部分：输入区（用 columns 做并排布局）

col1, col2 = st.columns([2, 1])    # 左边占 2 份，右边占 1 份

with col1:
    task_input = st.text_area("你要分析的文本或问题", height=100)

with col2:
    selected_models = []
    for label, model_id in AVAILABLE_MODELS.items():
        if st.checkbox(label, value=True):
            selected_models.append(model_id)

• st.columns([2, 1])：把页面分成左右两栏，宽度比例 2:1
• st.text_area：多行文本输入框
• st.checkbox：复选框，返回 True/False

第三部分：按钮与结果展示

if st.button("🚀 开始对比", type="primary"):
    # 调用模型
    results = {}
    for model_id in selected_models:
        try:
            result = call_model(task_input, model_id, system_prompt)
            results[model_id] = result
        except Exception as e:
            results[model_id] = {"error": str(e)}

    # 性能对比表格
    st.markdown("### 📊 性能对比")
    st.table(table_data)

    # 各模型回答（用 columns 并排展示）
    cols = st.columns(len(results))
    for col, (model_id, result) in zip(cols, results.items()):
        with col:
            st.markdown(f"#### {result['label']}")
            st.markdown(result["content"])

• st.button：按钮，点击返回 True，进入 if 分支
• st.table：表格，传字典列表即可
• st.columns + zip：动态分栏，有几个结果就分几栏

5.4.4　Streamlit 上手清单

想做什么	用什么组件
标题	st.title / st.header / st.subheader
说明文字	st.markdown / st.caption
单行输入	st.text_input
多行输入	st.text_area
数字输入	st.number_input
下拉选择	st.selectbox
多选框	st.checkbox / st.multiselect
按钮	st.button
显示文本	st.markdown / st.write
显示表格	st.table / st.dataframe
显示图片	st.image
进度条	st.progress
加载提示	st.spinner
成功/警告/错误	st.success / st.warning / st.error
分栏	st.columns
分隔线	st.divider

💡 学习建议：不用一次记住所有组件，用到的时候查表就行。本书所有案例都会用到的核心组件：text_input、text_area、button、markdown、columns、selectbox。掌握这 6 个，就能做出 80% 的 AI 应用界面。

---

5.5　实战体验：AI+X 多模型对比工具

5.5.1　Demo 是什么

AI+X 多模型对比工具：输入一个分析任务，同时调用多个国内大模型，把回答、耗时、Token 消耗并排展示，帮你直观对比不同模型的差异。

这个 Demo 一次性解决了本章的三个关键：

1. API 调用：封装 call_model 函数，安全读 Key、设置超时、做错误处理
2. 模型选择：三个模型并排调用，展示耗时与 Token，方便对比
3. 界面部署：用 Streamlit 搭建可演示的界面，包含输入、按钮、表格、分栏展示

5.5.2　获取代码

代码保存在 chapter5code/ 文件夹里：

chapter5code/
├── app.py              # 主程序（多模型对比工具）
├── requirements.txt    # 依赖清单
└── .env.example        # API Key 配置模板

5.5.3　配置并运行

第一步：安装依赖

cd chapter5code
pip install -r requirements.txt

第二步：配置 API Key

把 .env.example 复制为 .env，把里面的 your_siliconflow_api_key 换成你自己的真实 Key：

SILICONFLOW_API_KEY=sk-你的真实Key

第三步：启动应用

streamlit run app.py

浏览器会自动打开 http://localhost:8501，看到应用界面。

5.5.4　体验流程

第一步：填写分析任务

在左侧文本框输入一个分析任务，比如：

分析以下古诗的风格特点：《静夜思》床前明月光，疑是地上霜。举头望明月，低头思故乡。

右侧默认勾选三个模型，系统提示词保持默认即可。

第二步：点击"开始对比"

点击"🚀 开始对比"按钮，工具会逐个调用三个模型，并显示进度条。

第三步：查看对比结果

调用完成后，页面会展示三部分内容：

1. 性能对比表格：列出每个模型的耗时、Token 消耗、成功/失败状态
2. 各模型回答：三个模型并排展示，方便横向对比
3. 选模型建议：根据结果给出选择建议
   
   第四步：根据结果做决策

看结果对比，结合你的项目需求做选择。比如：

• 想要快速演示 → 选 Qwen2.5-7B
• 想要详细分析 → 选 Qwen3-8B 或 DeepSeek-R1
• 想要稳定可靠 → 避开容易超时的模型

5.5.5　代码走读：三个关键在代码里的位置

打开 app.py，对照本章讲的三个关键，看代码是怎么实现的：

关键	对应代码	看什么
API 调用	call_model 函数	Key 怎么读、超时怎么设、错误怎么处理
模型选择	AVAILABLE_MODELS 字典	怎么定义可选模型、怎么让用户勾选
界面部署	st.set_page_config 之后部分	怎么用 Streamlit 组件搭界面

这是学习 Vibe Coding 的重要方法：拿到一段能跑的代码，对照"它解决了什么问题"来读，比抽象地学语法高效得多。

5.5.6　用 TRAE 改造这个 Demo

学会本章三个关键后，你可以用 TRAE 改造这个 Demo，做成自己的项目。下面是几个改造方向：

改造方向一：换成你专业的分析任务

请把 chapter5code/app.py 的默认输入框文字，换成我专业的示例任务。
我的专业是 [你的专业]，一个典型的分析任务是 [描述任务]。
另外把系统提示词改成更符合我专业场景的描述。

改造方向二：增加模型选项

请在 AVAILABLE_MODELS 里增加更多硅基流动上的免费模型，
比如 GLM-4-9B、Yi-1.5-9B 等，让用户可以勾选更多模型做对比。

改造方向三：增加结果导出功能

请帮我添加一个"导出对比报告"按钮，点击后把对比结果（表格 + 各模型回答）
保存为 Markdown 文件，让用户下载。

改造方向四：支持图片输入（多模态）

请把工具改造成支持图片输入：用户上传一张图片，
调用硅基流动上的视觉模型（如 Qwen2.5-VL），分析图片内容。
对比文本模型和视觉模型的差异。

每个改造方向都能让你更深入地理解三个关键。Vibe Coding 的精髓就是：先跑通一个能用的，再一点点改造、扩展、深化。

---

本章小结

本章你学会了让 AI+X 项目"跑起来"的三个关键：

1. API 调用：四件套（URL、Headers、Body、Timeout）+ 安全（.env 读 Key）+ 错误处理（try-except 区分错误类型）。掌握这套，国内所有大模型你都会调用。
2. 模型选择：从质量、速度、成本三个维度对比模型，用"对比工具"拿数据说话。新手默认用 Qwen2.5-7B，分析类用 Qwen3-8B，推理类用 DeepSeek-R1。
3. 界面部署：用 Streamlit 把 AI 能力封装成可演示的界面。四件套（页面配置 + 标题 + 输入组件 + 输出结果）就能做出 80% 的 AI 应用。

这三个关键，是后续所有实战案例的基础。从第 6 章开始，我们将进入实战篇——按工科、经管、人文、艺术、医农、教育法律六大类，每类 2 个案例，带你做真正的 AI+X 项目。每个案例都会用到本章的三个关键，你会越来越熟练。

---

课后练习

基础题

1. 按照 5.5 节的步骤，运行 AI+X 多模型对比工具，输入一段你专业的文本，对比三个模型的回答差异。记录下三个模型的耗时、Token 消耗，思考为什么会有这种差异。
2. 把 Demo 的系统提示词改成你专业场景的描述（例如"你是一位专业的古诗风格分析师"），再次运行同一个任务，看看回答有什么不同。

进阶题

3. 用 TRAE 给 Demo 增加一个"导出 Markdown 报告"按钮，把对比结果保存为 .md 文件下载。提示词参考 5.5.6 节的改造方向三。
4. 用对比工具跑你专业的 5 个不同任务，记录每次三个模型的耗时和 Token 消耗，形成一张"模型性能对比表"。基于这张表，给你专业的项目推荐一个默认模型。

挑战题

5. 把 Demo 改造成"双模型对话对比器"——用户输入一句问题，两个模型同时回答，但让一个模型扮演"老师"、一个模型扮演"学生"，对比两者的回答视角差异。这种"角色对比"是人文社科类项目常用的研究方法。

---

本章代码清单

文件	路径	说明
主程序	chapter5code/app.py	多模型对比工具完整代码
依赖清单	chapter5code/requirements.txt	Python 依赖包列表
配置模板	chapter5code/.env.example	API Key 配置模板

运行环境要求

• Python 3.10+
• pip（Python 包管理器）
• TRAE（AI 编程工具）
• 硅基流动 API Key（免费注册获取）

常见报错

报错信息	可能原因	解决方法
ModuleNotFoundError: No module named 'streamlit'	依赖未安装	运行 pip install -r requirements.txt
SILICONFLOW_API_KEY 为 None	.env 文件未创建	在 chapter5code/ 目录下创建 .env 文件
HTTP 401 错误	API Key 错误	检查 .env 中的 Key 是否正确，有没有多余空格
HTTP 429 错误	请求太频繁	等几秒重试，或减少同时调用的模型数量
某个模型超时失败	网络波动或模型负载高	重新点击"开始对比"重试，错误处理会让其他模型继续跑
页面打不开	Streamlit 服务未启动	在终端运行 streamlit run app.py
中文乱码	终端编码问题	Windows 用 PowerShell，运行 chcp 65001 切换 UTF-8 编码