ci(workflows): restrict deploy workflow to main branch only

docs(zh-cn): enhance AI integration guide with practical tips and structure
2026-01-20 10:28:46 +08:00
parent 389c9126a1
commit f6195ee17a
2 changed files with 120 additions and 52 deletions
@@ -2,8 +2,10 @@
 name: Deploy VitePress site to Pages
 on:
-  # Runs on every push.
+  # Runs on pushes to main branch only
  push:
    branches:
      - main
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
@@ -53,10 +53,24 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 - **你发出去的内容**：通常包括“密钥（API Key）”和“你要生成什么”
 - **对方回给你的内容**：成功就给结果；失败会告诉你原因（比如“密钥不对”“余额不足”“参数写错”）
 ::: info 💡 学习建议
 建议你先把第 2/3 章的例子跑通一次。跑通之后再回来看这一节，你会更容易理解 Key、请求结构、模型名这些概念，也更容易定位常见报错（例如余额不足、密钥无效、参数写错）。
 :::
 ### 1.1 原型接入的黄金公式
 在原型阶段，你只要记住一句话就够了：
 > **拿到 API Key + 找到官方示例 + 让 AI IDE 帮你接到按钮上。**
 无论你接入的是文字模型还是图片模型，你做的事情本质上都一样：当用户点击按钮时，前端整理输入并发起请求；接口返回结果后，再把结果展示到页面上。
 ### 1.2 你至少要认识的 3 个词
 1. **API Key**：你的“通行证”，也是“钱包钥匙”。别人拿到它，就可以替你调用接口并产生费用。
 2. **Endpoint（请求地址）**：你把请求发到哪里（例如 `.../chat/completions`、`.../images/generations`）。
 3. **Model（模型名）**：你希望使用哪一个模型（同一家服务里通常会提供多个可选模型）。
 如果你想看更详细的 0 基础解释，可以看附录：[《API 入门（0 基础版）》](/zh-cn/appendix/api-intro)。
 ## 2. 接入文本 API（生成文字）
@@ -124,11 +138,11 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 <!-- TODO: 插入截图：原型中“生成文案/改写/总结”的入口（来自上一节的原型页面） -->
-### 2.3 接入 DeepSeek 文本API
+### 2.3 实操：接入 DeepSeek 文本 API（含截图）
 这一小节更“细一点”，把你在 AI IDE 里需要说清楚的话写出来。你照着做就行。
-**目标**：从 DeepSeek 拿到密钥 → 从文档复制示例 → 粘贴到 AI IDE → AI IDE 改代码 → 我们回到页面再次测试。
+**目标**：你需要先拿到 DeepSeek 的密钥，再从文档里复制一份可运行的请求示例，把它交给 AI IDE 生成代码改造，最后回到页面进行一次真实调用测试。
 你可以按下面的顺序来：
@@ -141,26 +155,23 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 3. **把“密钥 + 示例 + 入口说明”粘贴给 AI IDE**
   - 让它直接改项目，并要求它告诉你：改了哪些文件、怎么验证
 4. **你自己回到页面再次测试**
-   - 输入一条商品信息 → 点生成 → 看是否出现“真实生成”的文字
+   - 输入一条商品信息，点击“生成”，确认页面出现了真实返回的文字结果
   - 如果失败：把报错提示原样复制回 AI IDE，让它继续修复
-### 什么是 DeepSeek
+::: details 了解更多：DeepSeek 是什么？（可跳过）
 > 提示：文档里可能会出现 “LLM” 这个词。你可以先把它理解为“能生成文字的 AI 模型”，不影响你把 API 接进原型。
 ![](images/image16.png)
-> 📚 信息引用自 [DeepSeek Wiki](https://en.wikipedia.org/wiki/DeepSeek)
+你不需要先理解这些背景才能“接入 API”。但如果你想知道它为什么常被拿来举例，可以简单记两点：
->
+
-> **杭州深度求索人工智能基础技术研究有限公司**（**Hangzhou DeepSeek Artificial Intelligence Basic Technology Research Co., Ltd.**），以 **DeepSeek** 为商号，是一家开发大语言模型（LLMs）的中国人工智能（AI）公司。DeepSeek 总部位于浙江杭州，由中国对冲基金幻方量化（High-Flyer）拥有并资助。DeepSeek 由幻方量化的联合创始人梁文锋于 2023 年 7 月创立，他也同时担任这两家公司的 CEO。该公司于 2025 年 1 月推出了同名聊天机器人及其 DeepSeek-R1 模型。
+- DeepSeek 是一家做大语言模型（LLM）的公司。
->
+- 课程里使用它的原因很朴素：**文档清晰 + 接入路径典型**，适合练一次“从 Key 到按钮”的小闭环。
-> 让我们看看 DeepSeek 在 GPQA 基准排名中与其他顶级模型的表现对比。值得注意的是，DeepSeek 是一个开源（每个人都可以从互联网下载模型）模型，而其他常见模型如 Grok、Google Gemini 和 ChatGPT 都是闭源的。正如我们所见，DeepSeek 已经很大程度上接近了第一梯队的模型。
+
->
+![](images/image17.png)
-> ![](images/image17.png)
+
->
+:::
 > GPQA 是“研究生级 Google-Proof 问答基准”的缩写，这是一个用于科学问答任务的研究生级基准。以下是详细介绍。
 >
 > GPQA 包含 448 个多项选择题，涵盖生物学、物理学和化学的子领域，如量子力学、有机化学、分子生物学等。这些问题由 61 位持有博士学位或正在攻读博士学位的专家编写，并经过了严格的验证过程。
 ### 如何获取 DeepSeek API
@@ -228,7 +239,9 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 ## 3. 接入图片 API（生成图片）：从“提示词”到“图片展示”
-如果说大语言模型专注于理解、推理和分析我们不知道的所有事物；那么图像和视频模型则专注于生成——将你脑海中的所有想法转化为视觉现实。在今年的 AI 生成领域（2025），图像编辑和视频生成非常流行。你一定在抖音或 YouTube 上看过 AI 生成的可爱动物视频、AI 创建的角色照片、AI 生成的肖像拍摄、切玻璃苹果的视频等等。在上完今天的图像和视频课程后，你也完全有能力创建同样的内容！
+如果说大语言模型更擅长“理解与生成文字”，那么图像/视频模型更擅长“把你的描述变成视觉结果”。
 你在抖音、B 站或 YouTube 上看到的很多 “AI 海报 / AI 主图 / AI 角色图”，本质上都是同一条链路：你输入一句提示词，系统发起一次请求，最终返回一张图片。
 图片 API 的“接入链条”其实也不复杂。你可以先按 0 基础版本跑通一遍，再去追求更好的效果。
@@ -291,28 +304,38 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 ### 3.3 选择一个图片服务接入（示例）
-下面给出三个常见选择。你只需要先选一个跑通即可：跑通之后，再尝试替换成你更喜欢的模型。
+下面给出三个常见选择。建议你先选一个把链路跑通，再根据效果与成本做替换。
-在今天的课程中，我们需要生成大量的图像和视频。为了方便起见，我们将使用统一连接的云服务提供商，并将提供相应的示例代码与调用密钥。你只需要按照以下步骤操作，就可以在你的原型中接入图像/视频能力。
+| 侧重点 | 推荐先用谁 | 一句话理由 |
 | --- | --- | --- |
 | 想要“通用 + 文字渲染不错”，并且用起来更像“标准 API” | SiliconFlow（Qwen-Image） | 路径清晰，适合练“从示例到接入” |
 | 更偏设计生产（插画/品牌风格/海报/矢量感） | Recraft | 更像“设计工具 + API” |
 | 国内网络更稳定，想走火山引擎生态 | Seedream（Volcengine） | 访问与支付更贴近国内环境 |
 ::: tip ✅ 选型小原则
 建议你先把“生成图片”按钮跑通。跑通之后，再用同一段提示词切换不同模型做对比，这会比凭感觉讨论“哪个更强”更高效。
 :::
 ::: details （可选）课程截图：统一云服务的示例
 ![](images/image20.png)
 ![](images/image21.png)
 ![](images/image22.png)
 :::
-## 3.4 将 SiliconFlow Qwen-Image API 集成到 AI IDE 中
+
 ### 3.4 路线 A：SiliconFlow（Qwen-Image）
 在原型里，图片 API 最常见的落点是：**“生成主图 / 生成海报 / 生成配图”**。你需要做的事情很简单：把用户输入整理成一句话，请求图片 API，然后把返回的图片展示出来。
-### 什么是 SiliconFlow
+::: details 了解更多：什么是 SiliconFlow / Qwen-Image？（可跳过）
 > [Silicon Flow (硅基流动)](https://cloud.siliconflow.com/me/models) 成立于 2023 年 8 月，是一家世界领先的 AI 能力提供商。它提供 SiliconCloud（具有自研推理加速的大模型云平台）和 BizyAir（用于 AI 图像生成的 ComfyUI 插件）等核心产品，为客户提供 AI 基础设施能力，拥有战略合作伙伴关系，并持有顶级行业认证。
 >
 > ![](images/image26.png)
 ### 什么是 Qwen-Image
 > Qwen-Image 是一个强大的图像生成基础模型，能够进行复杂的文本渲染和精确的图像编辑。这是一个 20B MMDiT 图像基础模型，在复杂的文本渲染和精确的图像编辑方面取得了重大进展。实验表明，它在图像生成和编辑方面都具有很强的通用能力，在文本渲染方面表现尤为出色，尤其是中文。
 >
 > 从中文到英文，Qwen-Image 可以像 GPT-4o 或 Seedream 模型一样生成高质量的文本。
@@ -325,7 +348,9 @@ API 可以简单理解为：**你按对方要求的格式“发一个问题”
 >
 > ![](images/image30.png)
-### 如何获取 SiliconFlow Qwen-Image API
+:::
 #### A1. 获取 Key & 文档示例
 入口：<https://cloud.siliconflow.com/me/models>
@@ -377,19 +402,21 @@ curl --request POST \
 ![](images/image35.png)
 #### A2. 让 AI IDE 把它接进你的按钮
 你可以把「API Key + 官方请求示例 + 你的原型需求」发送给 AI IDE，并要求它帮你创建一个前端测试演示或直接改造当前项目。很快，你就能跑通 SiliconFlow 的基本 API 调用。
 <!-- TODO: 插入截图：AI IDE 中说明“我要把图像 API 接到原型的哪个按钮/页面” -->
 ![](images/image36.png)
-## 3.5 将 Recraft API 集成到 AI IDE 中
+### 3.5 路线 B：Recraft（更偏设计生产）
 如果你的原型更偏“设计生产”（例如生成品牌风格插画、营销海报、矢量风格素材），Recraft 往往会更顺手。接入方式与上一节完全一致：**拿到 Key + 找到官方示例 + 让 AI IDE 把示例落到你的按钮/页面里**。
 <!-- TODO: 插入截图：原型中 Recraft 的使用入口（例如“生成插画/生成海报”） -->
-### 什么是 Recraft
+::: details 了解更多：什么是 Recraft？（可跳过）
 > Recraft 是一款面向设计师、插画师和营销人员的 AI 工具——于 2022 年在美国成立，总部位于伦敦。它帮助生成/迭代视觉效果（图像、矢量艺术、3D 图形），具有高质量输出（任何文本大小/长度）、精确元素定位和品牌一致性设计等优势。受到 200 个国家/地区 300 多万用户（包括奥美、Netflix）的信任，并已创建了 3.5 亿多张图像，其团队旨在使其成为必备的设计师工具，确保创作者能够控制他们的 AI 辅助工作流程。
 >
@@ -398,8 +425,9 @@ curl --request POST \
 > ![](images/image38.png)
 >
 > ![](images/image39.png)
 :::
-### 如何获取 Recraft API
+#### B1. 获取 Key & 文档示例
 首先，我们仍然需要找到 API 入口以获取 API Key：<https://www.recraft.ai/profile/api>
@@ -413,6 +441,8 @@ curl --request POST \
 - <https://www.recraft.ai/docs/api-reference/usage>
 - <https://www.recraft.ai/docs/api-reference/guides>
 #### B2. 让 AI IDE 把它接进你的按钮
 在这里，我们可以直接复制官方文档中的请求示例，并粘贴到 AI IDE。
 ![](images/image41.png)
@@ -425,13 +455,13 @@ curl --request POST \
 ![](images/image42.png)
-## 3.6 将 Seedream API 集成到 AI IDE 中（针对中国用户）
+### 3.6 路线 C：Seedream（火山引擎，国内网络更稳）
 如果你希望使用国内网络更稳定、且效果不错的图像生成服务，可以考虑 Seedream（火山引擎）。思路同样不变：把它当成一个“图片生成 API”，接到你的原型按钮上即可。
 <!-- TODO: 插入截图：原型中 Seedream 的使用入口（例如“生成商品主图”） -->
-### 什么是 Seedream 4.0
+::: details 了解更多：什么是 Seedream 4.0？（可跳过）
 模型介绍：<https://seed.bytedance.com/en/seedream4_0>
@@ -444,8 +474,9 @@ curl --request POST \
 > ![](images/image45.png)
 >
 > ![](images/image46.png)
 :::
-### 如何获取 Seedream API - 火山引擎 (Volcengine)（针对中国用户）
+#### C1. 获取 Key & 示例（火山引擎 / Volcengine）
 我们将逐步演示如何将 Seedream API 集成到你的项目中（通过 AI IDE 辅助完成）。
@@ -485,7 +516,9 @@ curl --request POST \
 <!-- TODO: 插入截图：AI IDE 粘贴 Seedream 示例并完成接入 -->
-重要提示：这里的默认示例相对复杂。记得禁用“添加水印”选项和“流式响应”选项，以确保不生成水印且不会发生请求失败。
+::: warning ⚠️ 重要提示
 这里的默认示例相对复杂。记得禁用 **“添加水印”** 和 **“流式响应”**，以确保不生成水印且不会发生请求失败。
 :::
 ![](images/image54.png)
@@ -493,7 +526,14 @@ curl --request POST \
 ![](images/image55.png)
-## 4. 📚 作业：给你自己的抖音电商工作台加上 AI 能力
+## 4. 实战接入：把它接进你的工作台（作业）
 到这里，你已经分别跑通了：
 - 文本：页面触发一次调用，并把返回的文字结果展示出来
 - 图片：页面触发一次调用，并把返回的图片结果展示出来
 接下来要做的，就是把它们“固定”在你的产品原型里。这里追求的不是临时演示，而是你后续会继续迭代的那份代码。
 <el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
  <template #header>
@@ -543,35 +583,25 @@ curl --request POST \
  </ul>
 </el-card>
-## 下一步
+## 5. 模型选型：如何找到“当前更强”的 AI 模型
 当你把“生成文字”和“生成图片”都接入成功后，你的工作台就已经具备了最核心的 AI 能力雏形：**点击按钮 → 发请求 → 拿结果 → 展示出来**。
 接下来，你可以在这个内容生产工作台的基础上，继续扩展更多 AI 能力组合，例如：
 - **文字生成文字**：一键生成多版标题/卖点、自动改写、批量生成不同风格文案
 - **图片生成文字**：上传竞品/爆款截图，让 AI 自动总结卖点、提取关键信息、生成上新文案
 - **文字生成图片**：根据商品描述自动生成配图草稿（主图/海报/详情页配图）
 ## 5. 附录：如何找到“当前更强”的 AI 模型
 文字模型（也常被叫作“大语言模型”）的发展速度非常快，我们总是需要确保我们用的是表现更好的模型之一。通过以下两个网站，你可以很方便地看到“现在大家常用、评价也更好的模型”。
 一般来说，这类网站可以理解为 **“模型竞技场”**：它会把两个模型的输出放在一起，你投票选你更喜欢的那个。票数高的模型，通常意味着更多人觉得它“更好用”。
-此外，你偶尔可能会在这些大模型竞技场中看到神秘的匿名模型。通常，这些是来自 OpenAI 或 Google 等公司的内部测试模型。你可能有机会意外体验到最先进模型的能力！
+此外，你偶尔可能会在这些大模型竞技场中看到神秘的匿名模型（“Unknown Model”）。这通常意味着：有人把“内部测试模型”悄悄放进来做盲测，你可能有机会提前体验到更强的能力。
 ### 5.1 LMArena
 网站：<https://lmarena.ai/>
-简介：LMArena 最初由加州大学伯克利分校大模型系统组织（LMSYS）作为一个学术副项目推出，现已发展成为一家公司。它是一个开源的众包 AI 基准测试平台。
+LMArena 更适合用来判断“多数人更偏好哪个模型的回答”。投票越多、分数越高，通常意味着它在真实使用场景里更稳。
-它改变了传统的基于学科测试评估 AI 技术的方式，将评估权移交给社区用户。通过匿名和众包配对比较，它评估大规模模型。该平台支持超过 68 个模型，如 GPT-4o 和 Claude 3.5。
+一个简单的用法是：
-它使用 Elo 评分系统，可以更真实地反映用户对模型回答质量的评价。根据用户投票数据，它编制了一个排行榜，涵盖七个类别，包括文本/语言能力、Web 开发和视觉/图像理解。
+1. 直接看排行榜（Leaderboard）
-
+2. 先选一个你要做的方向（例如通用对话 / 编程 / 视觉）
-截至 2025 年 4 月（撰写时），它已记录了超过 300 万次比较，并评估了 400 多个模型，是非常流行的众包对比平台。
+3. 选 Top 3 里你能用的那个（能访问、价格能接受、延迟能接受）
 ![](images/image.png)
@@ -579,10 +609,46 @@ curl --request POST \
 网站：<https://artificialanalysis.ai/>
-Artificial Analysis 是领先的独立 AI 基准测试和分析平台。它专注于对 AI 模型和 API 提供商进行独立分析。该网站提供详细的数据和图表，可以帮助开发者、用户、研究人员和其他用户做出明智的选择。
+Artificial Analysis 更适合把“效果 / 价格 / 速度”放在同一张表里对比，你可以把它当作模型选型的参数表。
-通过比较不同 AI 模型的质量、性能、价格和其他关键指标，它帮助用户找到最适合其需求的 AI 模型解决方案。
+常用的用法是：
-其功能包括模型比较、质量评估、价格分析、性能测试和上下文窗口分析。它还提供了详细的用户指南和常见问题解答，涵盖各种类型模型的评估，如大语言模型、文本到图像模型和语音到文本模型。此外，它还提供了一个专注于模型基准的免费 API 和一个具有更全面数据的商业 API。
+1. 找到你关心的模型类别（文本 / 生图等）
 2. 看质量指标（Quality）+ 价格（Price）+ 延迟/吞吐（Latency/Throughput）
 3. 选一个“综合性价比”最符合你产品的
 ::: tip ✅ 建议
 不要凭感觉争论“哪个更强”。更可靠的做法是：用同一组输入同时测试 2~3 个模型，再结合榜单与价格做决定。
 :::
 ![](images/index-2026-01-19-23-36-57.png)
 ## 下一步
 <el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
  <template #header>
    <div style="font-weight: bold; font-size: 16px;">✅ 里程碑：你的工作台已经“能干活”了</div>
  </template>
  <p>
    你已经把“生成文字”和“生成图片”接入到了真实 API。现在它不是演示页面，而是一个能产出内容的工具。
  </p>
  <p>
    这一步的价值在于：你可以更快产出多版素材，并用同一套流程反复迭代，最后选出更适合投放与转化的版本。
  </p>
 </el-card>
 ### 接下来你要解决的是什么问题？
 以“电商素材工作台”为例，你通常会遇到三类真实需求：
 1. 你需要为同一个商品产出多版标题和卖点，用来适配不同渠道与不同人群。
 2. 你需要先有主图/海报的草稿方向，才能更快和设计对齐，减少反复沟通。
 3. 你需要从竞品图里提炼出结构与表达方式，再转成你自己的上新文案。
 ### 三个最常见的能力组合（建议按顺序做）
 1. **文字生成文字**：让工作台一次生成多版标题/卖点，并支持改写与风格切换，用来做备选与 A/B 测试。
 2. **文字生成图片**：把商品信息整理成提示词，先生成主图/海报草稿，用来快速确定方向。
 3. **图片生成文字**：上传竞品主图或爆款截图，提取卖点与结构，再生成更适合你商品的文案。