From f6195ee17a6b6c68a8f98bcc2da1657580710073 Mon Sep 17 00:00:00 2001 From: sanbuphy Date: Tue, 20 Jan 2026 10:28:46 +0800 Subject: [PATCH] ci(workflows): restrict deploy workflow to main branch only docs(zh-cn): enhance AI integration guide with practical tips and structure --- .github/workflows/deploy.yml | 4 +- .../1.3-integrating-ai-capabilities/index.md | 168 ++++++++++++------ 2 files changed, 120 insertions(+), 52 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0668a5d..5aba738 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -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: diff --git a/docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md b/docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md index 82f9263..66450bc 100644 --- a/docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md +++ b/docs/zh-cn/stage-1/1.3-integrating-ai-capabilities/index.md @@ -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 可以简单理解为：**你按对方要求的格式“发一个问题” -### 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) -> -> **杭州深度求索人工智能基础技术研究有限公司**（**Hangzhou DeepSeek Artificial Intelligence Basic Technology Research Co., Ltd.**），以 **DeepSeek** 为商号，是一家开发大语言模型（LLMs）的中国人工智能（AI）公司。DeepSeek 总部位于浙江杭州，由中国对冲基金幻方量化（High-Flyer）拥有并资助。DeepSeek 由幻方量化的联合创始人梁文锋于 2023 年 7 月创立，他也同时担任这两家公司的 CEO。该公司于 2025 年 1 月推出了同名聊天机器人及其 DeepSeek-R1 模型。 -> -> 让我们看看 DeepSeek 在 GPQA 基准排名中与其他顶级模型的表现对比。值得注意的是，DeepSeek 是一个开源（每个人都可以从互联网下载模型）模型，而其他常见模型如 Grok、Google Gemini 和 ChatGPT 都是闭源的。正如我们所见，DeepSeek 已经很大程度上接近了第一梯队的模型。 -> -> ![](images/image17.png) -> -> GPQA 是“研究生级 Google-Proof 问答基准”的缩写，这是一个用于科学问答任务的研究生级基准。以下是详细介绍。 -> -> GPQA 包含 448 个多项选择题，涵盖生物学、物理学和化学的子领域，如量子力学、有机化学、分子生物学等。这些问题由 61 位持有博士学位或正在攻读博士学位的专家编写，并经过了严格的验证过程。 +你不需要先理解这些背景才能“接入 API”。但如果你想知道它为什么常被拿来举例，可以简单记两点： + +- DeepSeek 是一家做大语言模型（LLM）的公司。 +- 课程里使用它的原因很朴素：**文档清晰 + 接入路径典型**，适合练一次“从 Key 到按钮”的小闭环。 + +![](images/image17.png) + +::: ### 如何获取 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 & 文档示例 入口： @@ -377,19 +402,21 @@ curl --request POST \ ![](images/image35.png) +#### A2. 让 AI IDE 把它接进你的按钮 + 你可以把「API Key + 官方请求示例 + 你的原型需求」发送给 AI IDE，并要求它帮你创建一个前端测试演示或直接改造当前项目。很快，你就能跑通 SiliconFlow 的基本 API 调用。 ![](images/image36.png) -## 3.5 将 Recraft API 集成到 AI IDE 中 +### 3.5 路线 B：Recraft（更偏设计生产） 如果你的原型更偏“设计生产”（例如生成品牌风格插画、营销海报、矢量风格素材），Recraft 往往会更顺手。接入方式与上一节完全一致：**拿到 Key + 找到官方示例 + 让 AI IDE 把示例落到你的按钮/页面里**。 -### 什么是 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： @@ -413,6 +441,8 @@ curl --request POST \ - - +#### 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”，接到你的原型按钮上即可。 -### 什么是 Seedream 4.0 +::: details 了解更多：什么是 Seedream 4.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 \ -重要提示：这里的默认示例相对复杂。记得禁用“添加水印”选项和“流式响应”选项，以确保不生成水印且不会发生请求失败。 +::: warning ⚠️ 重要提示 +这里的默认示例相对复杂。记得禁用 **“添加水印”** 和 **“流式响应”**，以确保不生成水印且不会发生请求失败。 +::: ![](images/image54.png) @@ -493,7 +526,14 @@ curl --request POST \ ![](images/image55.png) -## 4. 📚 作业：给你自己的抖音电商工作台加上 AI 能力 +## 4. 实战接入：把它接进你的工作台（作业） + +到这里，你已经分别跑通了： + +- 文本：页面触发一次调用，并把返回的文字结果展示出来 +- 图片：页面触发一次调用，并把返回的图片结果展示出来 + +接下来要做的，就是把它们“固定”在你的产品原型里。这里追求的不是临时演示，而是你后续会继续迭代的那份代码。