Agentforce Models API 开发者指南

四大核心能力

Models API 提供 Apex 类和 REST 端点，将你的应用连接到 Salesforce 合作伙伴的 LLM。所有调用都经过 Einstein Trust Layer。支持 1GP 和 2GP 托管包。所有请求受 Einstein Requests 使用计费约束。

通过 Apex 访问 Models API

Models API 在 aiplatform 命名空间中提供 Apex 类，从 Models REST API 规范自动生成。每种能力都有对应方法，含请求/响应对象。

Generate Text — 最简单的调用

aiplatform.ModelsAPI.createGenerations_Request request = new ...();
request.modelName = 'sfdc_ai__DefaultOpenAIGPT4OmniMini';
request.body.prompt = 'Generate a welcome email...';
// 输出: response.Code200.generation.generatedText

Generate Chat — 多消息对话

List<ModelsAPI_ChatMessageRequest> messages = new List<>();
// 添加 systemMessage (role='system') + userMessage (role='user')
request.body.messages = messages;
// 输出: response.Code200.generationDetails.generations

Generate Embeddings — 向量化

request.modelName = 'sfdc_ai__DefaultOpenAITextEmbeddingAda_002';
body.input = new List<String>{'Every day, once a day...'};
// 输出: response.Code200.embeddings

Submit Feedback — 质量反馈

feedbackRequest.feedback = 'GOOD';  // 或 'BAD'
feedbackRequest.feedbackText = '...';
feedbackRequest.source = 'HUMAN';
// 输出: response.Code202.message

异常处理：所有方法在出错时抛出 *ResponseException，通过 e.responseCode 检查 HTTP 状态。

通过 REST 访问 Models API

步骤 1 — 创建 External Client App

OAuth 范围：api、refresh_token/offline_access、sfap_api。启用 Client Credentials Flow 和 JWT 令牌。

步骤 2 — 生成 JWT Token

curl -X POST https://{my_domain}/services/oauth2/token \
  -d "grant_type=client_credentials&client_id={key}&client_secret={secret}"
// Response: access_token, instance_url, api_instance_url

步骤 3 — 调用 API 端点

四个必需 Header：

• Authorization: Bearer {token}
• Content-Type: application/json
• x-sfdc-app-context: EinsteinGPT
• x-client-feature-id: ai-platform-models-connected-app

curl -X POST 'https://api.salesforce.com/einstein/platform/v1/models/sfdc_ai__DefaultOpenAIGPT4OmniMini/generations' \
  --header 'Authorization: Bearer {token}' \
  --header 'x-sfdc-app-context: EinsteinGPT' \
  --header 'x-client-feature-id: ai-platform-models-connected-app' \
  --data '{"prompt": "Generate a story about James Lee..."}'

响应包含：generatedText、contentQuality（毒性分数）、parameters（Token 使用量）。401/404 错误：验证应用范围、完整 access_token、My Domain URL。

构建 LWC 和 Flow

四种集成模式

所有示例默认使用 sfdc_ai__DefaultOpenAIGPT4OmniMini 模型。这些是演示模式，非生产就绪代码。

速率限制和模型 API 名称

速率限制

超限返回 HTTP 429。Apex 方法也受 Apex Callout 限制。Agentforce 推理引擎在 Sandbox 中当前无速率限制（已知问题，可能变化）。

模型 API 名称模式

sfdc_ai__Default<Provider><ModelName>

• 命名空间：sfdc_ai
• 分隔符：__
• 配置：Default（或自定义配置名）

查找方式：AI Models → Generative 标签页 → 点击模型 → 详情中的 API 名称。REST 路径：/models/{modelName}/generations。Apex：request.modelName = '...'。

Trust Layer：语言、数据脱敏和毒性检测

语言和区域设置

• localization 载荷：defaultLocale + inputLocales（区域 + 概率）+ expectedLocales
• 提高数据脱敏和毒性评分的准确性
• 指南：单一语言用 defaultLocale；混合语言用 inputLocales；始终提供语言+区域

数据脱敏（Data Masking）

• Einstein Trust Layer 在发送给 LLM 之前对 PII 和 PCI 数据进行脱敏
• 将敏感值替换为占位符文本 → LLM 用占位符生成响应 → Trust Layer 反脱敏 → 你看到实际数据
• 审计追踪存储在 Data 360
• 启用脱敏时上下文窗口限制为 65,536 Token
• 关闭脱敏可使用完整上下文窗口
• 无 100% 准确率保证；跨区域用例可能影响检测

毒性评分（Toxicity Scoring）

• 对所有 LLM 生成自动执行
• 响应包含：scanToxicity.isDetected（布尔值）+ categories[] 分数（0-1）
• 六类检测：identity / hate / profanity / violence / sexual / physical
• 分数越高越可能有害；isDetected=true 表示高可信度有害
• 数据存储在 Data 360 供审查
• 指定正确的区域设置以获得最佳检测准确率

Models API 为你提供了安全、受管控的途径来访问世界领先的 LLM——通过 Apex 或 REST，配合完整的 Trust Layer 保护、灵活的速率限制和丰富的集成模式。