sap-cloud-sdk-ai

SAP Cloud SDK for AI

相关技能

• sap-cap-capire：用于构建使用 AI 服务的 CAP 应用，包括事件处理程序模式和异步大模型编排
• sap-ai-core：用于 AI Core 平台设置、编排配置和模型部署
• sap-dependency-security：有关升级 npm 软件包、锁文件策略和安全依赖工作流的加固指南

SAP AI Core、SAP Generative AI Hub 和 Orchestration Service 的官方 SDK。软件包版本已通过公共注册表验证；AI Core 租户执行情况和具体模型的可用性仍需在目标租户中验证。

何时使用此技能

在以下情况下使用此技能：

• 将 AI/大模型功能集成到 SAP BTP 应用中
• 构建聊天补全或嵌入功能
• 通过 SAP AI Core 使用经租户批准的 OpenAI、Claude、Gemini、Amazon、Mistral 或其他模型系列
• 实现内容过滤、数据掩码或文档依据
• 使用 LangChain 或 Spring AI 创建 Agent 工作流
• 通过 Prompt Registry 管理提示词
• 在 SAP AI Core 上部署 AI 模型

目录

• 快速入门
• 先决条件
• 连接设置
• 可用软件包
• 支持的模型
• 核心功能
• 捆绑资源

快速入门

注意：此技能使用 SAP Cloud SDK for AI JavaScript v2.11.0+ 和 Java v1.19.0+，版本依据来自 2026-06-15 的公共软件包注册表证据。如果你要从 v1.x 迁移，请参阅 V1 到 V2 迁移指南，了解重大变更。

JavaScript/TypeScript

npm install @sap-ai-sdk/orchestration@^2

import { OrchestrationClient } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: {
    model: { name: 'gpt-4o' },
    prompt: [{ role: 'user', content: '{{?question}}' }]
  }
});

const response = await client.chatCompletion({
  placeholderValues: { question: 'What is SAP?' }
});
console.log(response.getContent());

Java

<dependency>
  <groupId>com.sap.ai.sdk</groupId>
  <artifactId>orchestration</artifactId>
  <version>${ai-sdk.version}</version>
</dependency>

var client = new OrchestrationClient();
var config = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_4O);
var prompt = new OrchestrationPrompt("What is SAP?");
var result = client.chatCompletion(prompt, config);
System.out.println(result.getContent());

先决条件

• Node.js 20+（JavaScript）或 Java 17+（Java）
• SAP AI Core 服务实例（extended 或 sap-internal 计划）
• AI Core 中的 Orchestration deployment（默认资源组已包含此部署）

连接设置

BTP 运行时（Cloud Foundry/Kyma）

将 AI Core 服务实例绑定到你的应用。SDK 会通过 VCAP_SERVICES 或挂载的密钥自动检测。

本地开发

设置环境变量：

export AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'

或使用 CAP 混合模式：

# JavaScript
cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid

# Java
cds bind --to aicore --exec mvn spring-boot:run

有关详细连接选项，请参阅 references/connecting-to-ai-core.md

可用软件包

JavaScript/TypeScript

软件包	用途
@sap-ai-sdk/orchestration	聊天补全、过滤、依据
@sap-ai-sdk/foundation-models	直接访问模型（OpenAI）
@sap-ai-sdk/langchain	LangChain 集成
@sap-ai-sdk/ai-api	部署、构件、配置
@sap-ai-sdk/document-grounding	Pipeline、Vector、Retrieval API
@sap-ai-sdk/prompt-registry	提示词模板管理

Java

构件	用途
orchestration	聊天补全、过滤、依据
openai (foundationmodels)	直接访问 OpenAI 模型
core	基础连接
document-grounding	Pipeline、Vector、Retrieval API
prompt-registry	提示词模板管理

支持的模型

模型 ID 和版本因租户而异。在将示例复制到应用代码之前，请通过 SAP AI Launchpad Model Library 或 AI Core 模型列表 API 列出目标目录。

示例系列

• OpenAI：在获得授权的情况下，可使用 GPT 系列聊天、多模态、推理和嵌入模型
• Anthropic (AWS)：在获得授权的情况下，可使用 Claude 系列模型
• Amazon：在获得授权的情况下，可使用 Nova/Titan 系列模型
• Google：在获得授权的情况下，可使用 Gemini 系列模型
• Mistral：在获得授权的情况下，可使用 Mistral 系列模型

已弃用的模型（请使用替代模型）

已弃用	请改用
text-embedding-ada-002	text-embedding-3-small/large
gpt-35-turbo (all variants)	gpt-4o-mini
gpt-4-32k	gpt-4o
gpt-4 (base)	gpt-4o or gpt-4.1
gemini-1.0-pro	gemini-2.0-flash
gemini-1.5-pro/flash	gemini-2.5-flash
mistralai--mixtral-8x7b	mistralai--mistral-small-instruct

核心功能

流式聊天补全

// JavaScript
const stream = client.stream({
  placeholderValues: { question: 'Explain SAP CAP' }
});

for await (const chunk of stream.toContentStream()) {
  process.stdout.write(chunk);
}

// Java
client.streamChatCompletion(prompt, config)
    .forEach(chunk -> System.out.print(chunk.getDeltaContent()));

函数/工具调用

// JavaScript
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    parameters: { type: 'object', properties: { city: { type: 'string' } } }
  }
}];

const response = await client.chatCompletion({
  placeholderValues: { question: 'Weather in Berlin?' }
}, { tools });

const toolCalls = response.getToolCalls();

内容过滤

// JavaScript
import { buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  filtering: {
    input: buildAzureContentSafetyFilter({ Hate: 'ALLOW_SAFE' }),
    output: buildAzureContentSafetyFilter({ Violence: 'ALLOW_SAFE' })
  }
});

数据屏蔽

// JavaScript
const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  masking: {
    masking_providers: [{
      type: 'sap_data_privacy_integration',
      method: 'anonymization',
      entities: [{ type: 'profile-email' }, { type: 'profile-person' }]
    }]
  }
});

文档依据

// JavaScript
const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  grounding: {
    grounding_input: ['{{?question}}'],
    grounding_output: ['{{?context}}'],
    data_repositories: [{ type: 'vector', id: 'my-repo-id' }]
  }
});

CAP 集成

SDK 可与 CAP 事件处理程序原生集成。在 CAP 服务类中使用 OrchestrationClient，为 CAP 服务添加 AI 功能。

MTA 中的服务绑定：

resources:
  - name: my-ai-core
    type: org.cloudfoundry.managed-service
    parameters:
      service: aicore
      service-plan: extended

包含 AI 的 CAP 事件处理程序：

import { OrchestrationClient } from '@sap-ai-sdk/orchestration';
import cds from '@sap/cds';

export default class AnalysisService extends cds.ApplicationService {
  async init() {
    const client = new OrchestrationClient({
      promptTemplating: {
        model: { name: 'gpt-4o' },
        prompt: [
          { role: 'system', content: 'Analyze and categorize as JSON.' },
          { role: 'user', content: '{{?input}}' }
        ]
      }
    });

    this.on('analyzeText', async (req) => {
      const response = await client.chatCompletion({
        placeholderValues: { input: req.data.text }
      });
      return response.getContent();
    });

    return super.init();
  }
}

重要：生产环境中的大模型调用应使用异步处理。 大模型响应可能需要 30-60 秒，超过 BTP 负载均衡器的超时时间。请返回 202 Accepted，并在后台处理：

this.on('analyzeText', async (req) => {
  const entry = await INSERT.into('Results').entries({
    text: req.data.text, status: 'processing'
  });
  cds.spawn(() => processLLM(entry.id, req.data.text, client));
  return req.reply(202, { id: entry.id, status: 'processing' });
});

如需了解完整的 CAP + AI 集成指南，包括用于 RAG 的 HANA Vector 类型和提示词外部化，请参阅 sap-cap-capire 技能。

响应辅助工具

JavaScript SDK 提供辅助方法：

const response = await client.chatCompletion({ placeholderValues });

response.getContent();          // Model output string
response.getTokenUsage();       // { prompt_tokens, completion_tokens, total_tokens }
response.getFinishReason();     // 'stop', 'length', 'tool_calls', etc.
response.getToolCalls();        // Array of function calls
response.getDeltaToolCalls();   // Partial tool calls (streaming)
response.getAllMessages();      // Full message history
response.getAssistantMessage(); // Assistant response only
response.getRefusal();          // Refusal message if blocked

流式响应方法：

const stream = client.stream({ placeholderValues });
for await (const chunk of stream.toContentStream()) {
  process.stdout.write(chunk);
}
// After stream ends:
stream.getFinishReason();
stream.getTokenUsage();

高级主题

详细指南：

• 编排功能：references/orchestration-guide.md
• 基础模型（直接使用 OpenAI）：references/foundation-models-guide.md
• LangChain 集成：references/langchain-guide.md
• Spring AI 集成：references/spring-ai-guide.md
• AI Core 管理：references/ai-core-api-guide.md

---

附带资源

参考文档

• references/foundation-models-guide.md - 基础模型和定价
• references/ai-core-api-guide.md - AI Core 服务 API 参考
• references/orchestration-guide.md - 编排服务指南
• references/langchain-guide.md - LangChain.js 集成
• references/spring-ai-guide.md - Spring AI 集成
• references/agentic-workflows.md - Agent 工作流模式
• references/connecting-to-ai-core.md - 连接设置指南
• references/error-handling.md - 错误处理模式
• references/v1-to-v2-migration.md - V1 到 V2 迁移指南

版本信息

SDK	当前版本	Node/Java 要求
JavaScript	2.11.0+	Node.js 20+
Java	1.19.0+	Java 17+（建议使用 21 LTS）

版本依据：docs/project/package-evidence/2026-06-15.json。这仅为软件包注册表依据，不代表实时 AI Core 运行时依据。

注意：生成的模型类（位于 ...model 软件包中）可能会在次要版本中变更，但可以安全使用。

常见错误

错误	原因	解决方案
"Could not find service bindings for 'aicore'"	缺少 AI Core 绑定	绑定 AI Core 服务或设置 AICORE_SERVICE_KEY
"Orchestration deployment not found"	资源组中没有部署	在 AI Core 中部署编排服务，或使用其他资源组
内容过滤违规	输入/输出被拦截	调整过滤阈值或修改内容
超出令牌限制	响应过长	设置 max_tokens 参数

文档来源

请使用以下来源更新此技能：

• JS 文档：https://github.com/SAP/ai-sdk/tree/main/docs-js
• Java 文档：https://github.com/SAP/ai-sdk/tree/main/docs-java
• JS SDK：https://github.com/SAP/ai-sdk-js
• Java SDK：https://github.com/SAP/ai-sdk-java
• 发行说明：查看 docs-js/release-notes.mdx 和 docs-java/release-notes.mdx