Get Started with the Models API | Models API 入门

一、学习 Models API 基础知识（Learn the Basics of the Models API）

本单元讲概念。我们先介绍 Models API 及其四项能力——生成文本、生成嵌入、生成聊天、提交反馈——再看它如何与 Prompt Builder 互补，探索 DreamHouse Realty 用例，回顾信任原则与 Einstein Trust Layer，最后列出支持的模型。这是动手设置之前的基础。

学习目标（Learning Objectives）

完成本单元后，你将能够：

• 描述 Models API 能做什么——通过 REST 和 Apex 提供的四项能力。
• 解释何时使用 Models API——相对于 Prompt Builder 和 Agentforce。

Models API 简介（Introduction to the Models API）

Models API 提供 Apex 类和 REST 端点，把应用连接到 Salesforce 合作伙伴的大语言模型（LLM），包括 Anthropic、Google 和 OpenAI。你可以使用任何可在 AI Models（原 Einstein Studio）中配置的 Salesforce 启用模型。

Models API 通过 REST 端点和 Apex 方法提供四项能力，接下来逐一了解。

Models API 核心能力（Models API Key Capabilities）

四项能力定义 Models API：

• 生成文本（Generate text）：从单个 prompt 生成文本，适合简单、非对话式任务和测试模型能力。
• 生成嵌入（Generate embeddings）：嵌入是内容的数值表示（也叫嵌入向量），可用余弦相似度、欧氏距离、点积等数学运算衡量两段内容的语义相似度，常用于检索增强生成（RAG）和语义搜索。
• 生成聊天（Generate chat）：为聊天对话生成消息，可用消息列表而非单个 prompt，每条消息代表对话历史的一部分。
• 提交反馈（Submit feedback）：对 Models API 生成的文本提供反馈，数据存储在 Data 360 中，用于审查响应质量并更新请求或模型配置。

如何使用 Models API（How to Use the Models API）

乍一看 Models API 与 Einstein Generative AI Prompt Builder 类似，但它是为灵活性与可扩展性设计的，与现有 Salesforce AI 产品互补。Prompt Builder 和 Prompt Template Connect API 擅长快速 prompt 管理，Agentforce 提供交互式聊天体验；Models API 则提供嵌入、带历史记录的聊天生成等额外功能，让开发人员能架构自定义 AI 应用。

现实示例：DreamHouse Realty 需要让员工了解本地和全国的房产市场状况。开发人员 Maria Garza 正在构建一个内部仪表板，用 Models API 分析外部 Housing Market API 的数据并总结给员工。她先专注第一步：设置环境，创建一个使用 Models API chatGenerations 端点的简单仪表板。

维护信任（Maintaining Trust）

信任是 Salesforce 的第一价值。Salesforce Einstein 生成式 AI 解决方案基于可信生成式 AI 的五项原则：

• 准确性（Accuracy） · 安全性（Safety） · 透明性（Transparency） · 赋能（Empowerment） · 可持续性（Sustainability）

Salesforce 还与 OpenAI 等 LLM 提供商有零数据保留协议，使用生成式 AI 时无需担心私有数据被第三方存储。

所有 Models API 调用都经过 Einstein Trust Layer——内置于 Salesforce 平台的安全 AI 架构，包含协议、安全技术、数据与隐私控制。生成调用会自动执行数据脱敏和毒性评分，API 返回是否检测到毒性的标志及分数信息，这些信息也存储在 Data 360 中。

Einstein Trust Layer 不能替代人工判断。若要与客户分享生成式 AI 输出，务必审查所有响应的准确性、偏见和毒性。

支持的模型（Supported Models）

Models API 支持多家提供商的大语言模型，如 Amazon Bedrock、Azure OpenAI、OpenAI 和 Google 的 Vertex AI。

Models API 还支持 AI Models 的 BYOLLM（bring your own LLM）功能：从支持的提供商添加基础模型、配置自己的模型实例、用你自己的凭据连接。虽然推理由客户模型处理，但请求仍通过 Models API 路由，Trust Layer 功能完全支持。

有关直接通过 Models API 可用及支持 BYOLLM 的模型完整列表，请参考本单元资源部分的 Supported Models 页面。

二、准备访问 Models API 的 Org（Prepare Your Org to Access the Models API）

本单元是环境设置。Maria 需要设置 org 和开发环境。我们注册带 Einstein Generative AI 的试用 org、重置密码、启用 Einstein、安装 Salesforce CLI 与 VS Code 扩展、创建 Salesforce DX 项目，并授权 AI Playground。这为构建仪表板打下基础。

注册试用 Org（Sign Up for a Trial Org）

完成本项目需要一个特殊的限时自定义 playground，包含 Einstein AI 和 Data 360：

1. 点击 Create Playground，新 org 自动附加到你的 Trailhead 账户。
2. 记下 org 的到期日期，并在此之前完成本 badge。

重置密码：启动 Trailhead Playground（点击 Launch），进入 Setup，在 Quick Find 搜索 Users，在用户列表找到你的名字并勾选，记下用户名，点击 Reset Password(s) 和 OK，点击邮件中的链接，输入并确认新密码，点击 Change Password。

注意：这个自定义 playground 专为本 badge 的挑战设计，可能不适用于其他 badge。创建时把用户名和密码存在安全处，连接 VS Code 时需要这些凭据。

接着启用 Einstein：进入 Setup，搜索 Einstein Setup，确保 Turn on Einstein 开关为 On。为确保 Lightning web 组件部署后立即可见，还需关闭浏览器缓存：进入 Setup，搜索 Session Settings，在 Caching 下取消勾选「Enable secure and persistent browser caching to improve performance」。

安装 Salesforce CLI（Install the Salesforce CLI）

Salesforce CLI 用于控制 Salesforce 应用的完整生命周期：创建开发与测试环境、在 org 与版本控制系统（VCS）间同步源代码、执行测试。

1. 从 Salesforce CLI 页面安装。
2. 从命令行运行更新命令，确认已正确安装且为最新版本。

安装 VS Code 扩展（Install VS Code Extensions）

Visual Studio Code 是 Salesforce 开发人员的首选代码编辑器，免费、开源，支持 Windows、Linux 和 macOS。

1. 下载并安装最新版 VS Code（已有则无需重装）。
2. 启动 VS Code，点击左侧工具栏的 Extensions 图标。
3. 搜索 Salesforce Extension Pack 并点击 Install。

该扩展包提供语法高亮、代码补全以及后续用到的 SFDX 命令。

创建项目（Create a Project）

创建 Salesforce DX 项目：

1. 打开命令面板（Ctrl+Shift+P / Cmd+Shift+P）。
2. 输入 SFDX，选择 SFDX: Create Project。
3. 按 Enter 接受标准选项。
4. 输入项目名 ModelsAPILWC，按 Enter。
5. 选择项目存储文件夹，点击 Create Project。

你会看到包含 .husky 和 .sfdx 子文件夹的基础项目结构。

授权你的 AI Playground（Authorize Your AI Playground）

创建 Lightning web 组件前，需把 AI Playground 连接到 VS Code 环境。

1. 在 VS Code 打开命令面板，输入 SFDX，选择 SFDX: Authorize an Org。
2. 按 Enter 接受 Project Default 登录 URL 选项。
3. 按 Enter 接受默认别名（在浏览器中打开 Salesforce 登录）。
4. 用 AI Playground 凭据登录，如提示允许访问则点击 Allow。

浏览器认证后，CLI 会记住你的凭据。注意：要在本模块之外访问 Models API，需要启用 Data 360 和 Einstein Generative AI 的可正常工作的开发环境。本挑战只检查 Setup 中是否启用了 Einstein，但前面所有步骤都是下一单元构建仪表板所必需的。

三、创建 Models API Lightning Web 组件（Create a Models API Lightning Web Component）

本单元是构建。Maria 创建自定义 Apex 类和接地数据类，用 HTML、CSS、JavaScript 和元数据构建 Lightning web 组件，部署到 AI Playground，并放到 Lightning App Builder 主页上。最终 Models API 仪表板在 Sales 主页上线。

创建 Models API Apex 类（Create Models API Apex Classes）

首先创建 Apex 类：

1. 在 VS Code 右键 force-app/main 下的 classes 文件夹，选择 SFDX: Create Apex Class，命名 DashboardController。
2. 删除新类默认的五行代码（本模块提供完整代码示例，无需默认代码）。
3. 在 DashboardController.cls 中粘贴调用 Models API chatGenerations 端点的代码。
4. 按 Ctrl+S / Cmd+S 保存。

你可能会看到「没有名为 HousingData 的类」的错误——这是预期的，接地数据在下一步作为演示用途的静态类添加。

创建接地数据类（Create a New Class for Grounding Data）

为了让 Maria 的 Models API 仪表板正常工作，她需要用相关房产市场数据接地 LLM。创建一个新类并填充数据，供 DashboardController 引用：

1. 右键 classes 文件夹，选择 SFDX: Create Apex Class，命名 HousingData。
2. 在 HousingData.cls 中粘贴提供的房产市场数据代码。
3. 按 Ctrl+S / Cmd+S 保存。
4. 再次右键 classes 文件夹，选择 SFDX: Deploy This Source to Org。
5. 在集成终端的 Output 标签页查看部署结果，成功会显示 Deployed Source 消息，列出上传到 org 的四个文件。

演示用途中数据是 LWC 内的本地文件；正式实现中，此步数据应从房产市场 API 动态检索。

构建 Models API Lightning Web 组件（Build a Models API Lightning Web Component）

现在构建 Lightning web 组件。打开命令面板，选择 SFDX: Create Lightning Web Component，命名 modelsAPIDashboard，按 Enter 接受默认 force-app/main/default/lwc。然后逐个添加文件：

• HTML 文件 modelsAPIDashboard.html——粘贴提供的标记代码。
• CSS 文件 modelsAPIDashboard.css——新建并粘贴样式代码。
• JavaScript 文件 modelsAPIDashboard.js——粘贴调用 Apex 控制器的代码。
• 元数据 文件 modelsAPIDashboard.js-meta.xml——设置 targets，让组件能放到各 Lightning Experience 页面。

每个文件都来自提供的代码示例，逐个保存。

部署到你的 AI Playground（Deploy to Your AI Playground）

1. 右键 lwc 下的 modelsAPIDashboard 文件夹。
2. 点击 SFDX: Deploy This Source to Org。
3. 在集成终端的 Output 标签页查看部署结果，成功会显示 Deployed Source 消息列出上传的文件。

组件已部署到 org，最后一步是把它放到页面上供用户查看。

在 Lightning App Builder 中编辑页面（Edit Page in Lightning App Builder）

最后一步是把组件放到主页上：

1. 打开命令面板，选择 SFDX: Open Default Org，在浏览器打开 AI Playground。
2. 点击齿轮图标，选择 Setup。
3. 在 Quick Find 搜索 Home（Feature Settings 部分），把 Advanced Seller Home 设为 Inactive。
4. 搜索 Lightning App Builder，点击 New 创建新 Lightning 页面（Playground 中现有 Sales Home 页面被锁定无法编辑）。
5. 选择 Home Page，点击 Next。
6. 输入标签 Home_Page_Default，点击 Next。
7. 选择布局（如 Standard Home Page），点击 Done。
8. 滚动到组件列表底部 Custom 部分，把 modelsAPIDashboard 组件拖到页面画布顶部。
9. 点击 Save，提示激活时点击 Activate，选择 Org Default 标签页，点击 Assign as Org Default，再点击 Save 确认。
10. 从 App Launcher 搜索并选择 Sales，即可查看带 Models API LWC 的新主页。

恭喜！你创建了第一个 Models API Lightning web 组件。DreamHouse Realty 现在在 Sales 主页上有了仪表板组件，销售团队可随时了解当前房产市场趋势。

---

文章来源：Trailhead - Get Started with the Models API