Agentforce Models API 开发者指南 | Apex+REST+LWC 完整参考

Models API 概览

Models API 提供 Apex 类和 REST 端点，连接你的应用到 Anthropic、Google、OpenAI 等合作伙伴的 LLM。支持所有可在 AI Models 中配置的 Salesforce 启用模型。所有调用经 Einstein Trust Layer 路由。支持 1GP 和 2GP 托管包。

注意：所有 Models API 请求受 Salesforce Einstein Requests 使用和计费费率约束。参见 Usage and Billing 和 Rate Card。

四大核心能力

能力	Apex 方法	说明
Generate Chat	`createChatGenerations`	基于消息列表（user/system/assistant 角色）生成对话响应。适合多轮对话场景
Generate Embeddings	`createEmbeddings`	生成文本的向量表示。用于 RAG 和语义搜索（cosine similarity/Euclidean distance/dot product）
Generate Text	`createGenerations`	从单条 Prompt 生成文本。适合简单非对话任务和模型能力测试
Submit Feedback	`submitFeedback`	提交对生成文本的反馈（GOOD/BAD + 文本说明）。数据存入 Data 360 用于质量审查

通过 Apex 访问 Models API

Models API 的 Apex 类使用 External Services 框架从 REST API 规范自动生成。Apex 方法在 aiplatform 命名空间的 ModelsAPI 类中。受 Apex Callout Limits 约束。

Apex 方法与代码示例

Generate Text（文本生成）

aiplatform.ModelsAPI.createGenerations_Request req = new aiplatform.ModelsAPI.createGenerations_Request();
req.modelName = 'sfdc_ai__DefaultOpenAIGPT4OmniMini';
aiplatform.ModelsAPI_GenerationRequest body = new aiplatform.ModelsAPI_GenerationRequest();
req.body = body;
body.prompt = 'Generate a welcome email for the new developer Jane Doe.';
try {
    aiplatform.ModelsAPI modelsAPI = new aiplatform.ModelsAPI();
    aiplatform.ModelsAPI.createGenerations_Response res = modelsAPI.createGenerations(req);
    System.debug('Generated: ' + res.Code200.generation.generatedText);
} catch(aiplatform.ModelsAPI.createGenerations_ResponseException e) {
    System.debug('Error: ' + e.responseCode);
}

Generate Chat（对话生成）— 含角色消息列表

List messages = new List();
aiplatform.ModelsAPI_ChatMessage sysMsg = new aiplatform.ModelsAPI_ChatMessage();
sysMsg.role = 'system'; sysMsg.content = 'You are a helpful assistant.';
messages.add(sysMsg);
aiplatform.ModelsAPI_ChatMessage userMsg = new aiplatform.ModelsAPI_ChatMessage();
userMsg.role = 'user'; userMsg.content = 'Write a haiku about recursion.';
messages.add(userMsg);
// req.modelName = '...'; req.body.messages = messages;
// res.Code200.generation.generatedText 获取响应

Submit Feedback（反馈）

aiplatform.ModelsAPI.submitFeedback_Request req = new aiplatform.ModelsAPI.submitFeedback_Request();
aiplatform.ModelsAPI_FeedbackRequest fb = new aiplatform.ModelsAPI_FeedbackRequest();
fb.id = 'unique-feedback-id'; fb.generationId = 'generation-uuid';
fb.feedback = 'BAD'; fb.feedbackText = 'Response was confusing';
fb.source = 'HUMAN'; req.body = fb;
aiplatform.ModelsAPI.submitFeedback_Response res = modelsAPI.submitFeedback(req);

提示：Apex 测试参考 External Services 框架测试指南。Models API 的 Apex 类基于此框架。

通过 REST 访问 Models API

最快入门方式：Postman Collection。

REST 设置：App、JWT 与 API 调用

Step 1：创建 External Client App

OAuth Scopes：api（用户数据访问）、refresh_token, offline_access、sfap_api（访问 Salesforce REST API 平台）。启用 Client Credentials Flow + Issue JWT Web Token。Policies → 设置 Run As 用户。

Step 2：生成 JWT Token

获取 Consumer Key + Secret → 调用 Token 端点：

curl -X POST https://{MY_DOMAIN}/services/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id={KEY} -d client_secret={SECRET}

# 使用 Token 调用 API
curl https://{INSTANCE}/services/data/v66.0/einstein/llm/generations \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"model":"sfdc_ai__DefaultGPT41","prompt":"Summarize this case...","params":{"temperature":0.7}}'

端点：Generate Text/Chat/Embeddings 均可通过 REST 调用。完整参考见 Models REST API Reference。

构建 LWC 与 Flow

Models API 的 Apex 类可在 Lightning Web Components 和 Flow 中使用，将 AI 能力嵌入 UI 和业务流程。

LWC 与 Flow 示例

LWC 集成：通过 imperative Apex（@wire 或直接调用）连接 Models API。例如创建"AI Summarize"按钮 → 点击调用封装 Models API 的 Apex 方法 → 显示 LLM 生成的摘要。

Flow 集成：创建 @InvocableMethod Apex 类封装 Models API 调用 → 在 Flow Builder 中作为 Action 使用。例如：Case 创建后 → Flow 触发 → 调用 Models API 生成分类建议 → 写入自定义字段。

详细的 LWC 和 Flow 构建指南参见 Build Lightning Web Components and Flows with Models API。

速率限制、API 名称与反馈

速率限制与模型 API 名称

速率限制：Models API 受 Einstein Requests 配额约束。每个 Generation/Chat/Embeddings 调用消耗 1+ Requests。具体配额取决于 Org 类型和许可证。参见 Usage and Billing 和 Rate Limits for Models API。

模型 API 名称查找：AI Models → Generative 选项卡 → 点击已配置模型名称 → 详情页显示 API 名称（格式 sfdc_ai__Default...）。任何 Salesforce-Managed 或自定义配置的模型都可通过此方式获取 API 名称。

反馈机制详解

每个反馈调用需两个 ID：id（唯一标识此反馈）和 generationId（标识反馈目标的 Generation UUID）。可提供：feedback（GOOD/BAD）、feedbackText（自由文本，存储时截断至 1024 字符）、source（HUMAN/AUTO）。数据存入 Data 360 用于审计和质量改进。

// REST Feedback Body
{"id":"feedback-uuid","generationId":"gen-uuid","feedback":"BAD","feedbackText":"The summary was confusing","source":"HUMAN"}

Trust Layer：语言、脱敏与毒性检测

所有 Models API 调用经过 Einstein Trust Layer，提供多层保护：

多语言支持：通过 localization 负载指定 defaultLocale（如 en_US）和 inputLocales 列表（含 probability 权重）。支持 ISO 语言代码和语言_国家组合格式。正确指定可提升数据脱敏和毒性检测的准确性
数据脱敏（Data Masking）：自动识别并脱敏 PII 数据（SSN/信用卡号/邮箱/电话）。指定正确的语言/区域可显著提升脱敏准确率
毒性检测（Toxicity Scoring）：检测 LLM 输出中的有害内容。正确配置 localization 可提高检测精度
零数据保留：与第三方 LLM 供应商的协议确保你的数据不被保留
审计追踪：反馈数据 + Generation 日志存入 Data 360（Event Log + Audit & Feedback）

Localization 负载示例

{"localization":{"defaultLocale":"en_US","inputLocales":[{"locale":"en_US","probability":0.6},{"locale":"es_ES","probability":0.4}]}}

参见：Specify Languages and Locales with Models API、Data Masking、Toxicity Confidence Scoring、Trust Layer Region and Language Support。