08 · SAP AI Core / Generative AI Hub:完整图文教程
目标:在 SAP AI Core 上跑通第一个大模型调用,把提示词做成可版本化的模板,再做一次基于自有文档的 grounding(检索增强生成)。 预计:3–5 小时 | 难度:中高 | 前置课程:AIG00–AIG03、HAML01–HAML04
你会做出什么
一条从零到能演示的完整链路:
BTP 子账户里的 SAP AI Core 服务实例(extended plan)+ SAP AI Launchpad 订阅;
AI Launchpad 里属于你自己团队的 resource group;
在 Model Library 一键部署一个对话模型,在 ML Operations 里为 embedding 模型创建 configuration + deployment;
用 Chat 和 Prompt Editor 把提示词调好,并存成带版本号的提示模板;
在本地(或 BAS)用 Python + Generative AI Hub SDK 通过 orchestration service 的部署 URL 调用模型;
把一份 CSV 业务文档向量化写进 SAP HANA Cloud 的向量表,用
COSINE_SIMILARITY检索 + 提示模板做 grounding,让模型"基于你的文档"回答;最后按清理清单把 deployment、configuration、服务密钥逐个收掉,避免持续计费。
跑通之后,你手上会有这些可验证的产物:
ML Operations → Deployments里至少两个 RUNNING 的 deployment(一个 LLM、一个 embedding);Generative AI Hub → Prompt Management里一条保存过的 prompt,能看到它的历史版本;一个能跑的 Jupyter notebook,包含
get_embedding()、run_vector_search()、ask_llm()三个可复用函数;一份 10 题的小评测记录(正确率 / 是否引用到正确文档片段);
一张清理完成截图清单,证明没有遗留计费资源。

读法说明:本教程按操作顺序编排,前一步的"验证"没通过就不要进入下一步。AI Core 里创建 deployment、configuration 都按"创建即计费"对待,练习结束务必执行「验收与清理」一节。
架构与原理
资源层级:从子账户到一次模型调用
SAP AI Core 是在 SAP BTP 上跑的 AI 运行时,它把"模型"当成一种可部署的资源来管理。理解下面 8 个概念,后面每一步点哪个按钮就都清楚了。
概念 |
一句话解释 |
本教程里的示例值 |
|---|---|---|
子账户(subaccount) |
BTP 里隔离用户、配额与服务的单元 |
你的培训/试用子账户 |
服务实例(service instance) |
在子账户里开通的一份服务 |
SAP AI Core,plan 选 extended(GenAI Hub 需要) |
服务密钥(service key) |
服务实例的一组 OAuth 客户端凭据 + API 地址 |
一个 JSON 文件 |
resource group(资源组) |
隔离 AI 资源与工作负载的命名空间,场景与可执行项在组间共享,deployment 与 configuration 在组内隔离 |
|
scenario(场景) |
一类 AI 任务的集合 |
|
executable(可执行项) |
场景里真正能跑的实现模板 |
|
configuration(配置) |
"用哪个 executable + 哪些参数"的配方 |
|
deployment(部署) |
把 configuration 跑起来,得到一个可调用的端点 |
|
一次调用的链路可以画成这样(文字版):
你的代码 / AI Launchpad UI
│ ① 用服务密钥换 OAuth token
▼
SAP AI Core 认证 (AICORE_AUTH_URL)
│ ② 带 token + 资源组请求部署端点
▼
resource group ──► deployment(RUNNING)──► 模型提供方(OpenAI / Google / Amazon / SAP 开源模型…)
关键规则有三条,踩坑大多源于没记住它们:
场景与可执行项共享,资源隔离:
foundation-models、orchestration这些 scenario 在所有 resource group 都能看到;但你创建的 configuration 与 deployment 只属于当前选中的 resource group。每个请求都要带资源组:用 REST 调用时是 HTTP 头
AI-Resource-Group: <你的资源组>;用 SDK 时是配置项AICORE_RESOURCE_GROUP。带错资源组会得到 404,而不是 403。deployment 状态机:
UNKNOWN → PENDING → RUNNING,失败会停在UNKNOWN/DEAD。只有 RUNNING 才有可用 URL,PENDING时刷新页面拿不到端点属正常。
Generative AI Hub 与 orchestration service
Generative AI Hub 是 AI Core 上"开箱即用大模型"的那层能力,按用量计费。它提供两类用法:
直接部署单个模型:
Generative AI Hub → Model Library里点一次Deploy,就能得到一个模型端点,适合快速验证、Chat 里试 prompt;部署 orchestration service:只部署一个 proxy,用统一的 API 串联"检索 → 模板 → 数据脱敏 → 内容过滤 → 模型配置 → 输出过滤"六个环节,之后换模型只改配置、不改代码。

这张图值得记住,因为它解释了为什么企业项目最终都会用 orchestration:
Grounding(检索):从数据仓库/向量库取相关片段;
Templating(模板):把用户输入填进版本化的提示模板;
Data Masking(脱敏):把 PII(身份证、邮箱、IP 等)在发给模型前遮掉;
Input / Output Filtering(内容过滤):拦截有害内容;
Model Configuration(模型配置):指定模型与 temperature、max tokens 等参数。
grounding 的调用链(RAG)
"模型能回答"和"模型答对"之间差的就是 grounding。RAG(Retrieval-Augmented Generation,检索增强生成)把外部知识在提问时塞进 prompt,而不是把知识训练进模型。

本教程用到的具体链路是:
阶段 |
做什么 |
用到的组件 |
|---|---|---|
① 入库 |
读 CSV 文档,按行拆成主题片段 |
Python |
② 向量化 |
调 |
Generative AI Hub SDK |
③ 存储 |
写进 HANA 表,向量列类型 |
SAP HANA Cloud + |
④ 检索 |
把问题也向量化,按 |
SQL: |
⑤ 生成 |
把 Top-K 片段填进提示模板,调用 LLM |
|
一句话记住各环节的职责:embedding 负责"找得到",prompt 模板负责"说得清",LLM 负责"讲得好"。 三个环节任何一环坏了,最终回答都会像"胡说",但排查方法完全不同(见文末 FAQ)。
计费、配额与区域:动手前必须知道的三件事
按用量计费的不只是 token:LLM 调用按输入/输出 token 计费,embedding 按文本量计费;此外 deployment 只要处于 RUNNING 就可能有资源占用成本,所以"建了不删"是新手最常见的浪费。练习时给自己定个规矩:每建一个 deployment,就在纸上记下它,收尾时逐个交叉核对。
配额(quota)决定你能不能部署:AI Core 子账户通常对"同时运行的 deployment 数量"与"模型族"有配额限制。部署失败时,除了看参数,也要看是否已经顶到配额上限——把不用的 deployment 停掉往往立刻就能建成功。
区域决定模型清单:不同区域的 AI Core 提供的模型与版本不完全一样(这也是为什么原文要求"以你系统实际为准")。如果你的租户里没有某个模型,最省事的做法是换一个同能力的模型(比如用 Gemini / Claude / Mistral 替代 GPT 系列),而不是折腾区域迁移。
准备工作
账号与权限
一个可用的 SAP BTP 子账户(试用账号也可以,但 Generative AI Hub 需要 AI Core 的 extended plan,free tier 通常只够跑 notebook 级练习,具体以你所在环境的服务计划为准)。
子账户下已创建 SAP AI Core 服务实例,已订阅 SAP AI Launchpad 应用。
你的 BTP 用户具备该子账户的 管理员或 Space Developer 类权限,能创建服务密钥、能打开 Launchpad。
可访问 SAP HANA Cloud 或 HANA 向量存储(做 grounding 时需要):拿到 host、port、用户名、密码,并且该用户有 建表 / 写数据 权限。
(可选)一个 Reddit 账号与 Reddit API 的 client id / secret,用于"实时数据做 RAG"那一步;没有就跳过该步骤的动手部分,只看思路。
本地工具
浏览器(Chrome / Edge,建议开一个无痕窗口专门跑练习,避免缓存干扰)。
Python 3.10 或更高(低于 3.10 请先升级,SDK 依赖需要);以及
pip。编辑器:VS Code 或 Jupyter/JupyterLab 任选;如果不想本地装,可用 SAP Business Application Studio 的 dev space(教程第 26 步会建)。
命令行工具(二选一即可):
btpCLI(SAP BTP 命令行),用于查服务实例/密钥;cfCLI(Cloud Foundry),如果 AI Core 实例建在 CF 环境,用它创建实例与密钥最直接。
curl(macOS/Linux 自带,Windows 用 PowerShell 的Invoke-RestMethod或 Git Bash)。
时间与配额预估
按本教程完整做一遍的时间分布大致是:环境与资源组 30–40 分钟、模型部署与 Chat/Prompt Editor 60–90 分钟、Python 环境与 SDK 40 分钟、HANA 建表与 RAG 代码 60–90 分钟、Reddit 与代码生成 40 分钟、orchestration 30–40 分钟、清理 15 分钟。若只做主线(跳过第 24、25、26、27、30 步),3 小时左右可以完成。
配额上,本教程最少需要 2 个同时 RUNNING 的 deployment(一个对话模型、一个 embedding 模型),做 orchestration 时再加 1 个 proxy 部署。如果子账户配额紧张,可以"用完一个停一个":先建 embedding → 跑完入库 → 停掉 → 建对话模型 → 跑问答。
数据集与仓库
官方示例仓库
SAP-samples/ai-core-samples(含 RAG 练习代码与GRAPH_DOCU_2503.csv);CodeJam 练习仓库
SAP-samples/generative-ai-codejam(第 26 步在 BAS 里克隆);一份小型业务文档(PDF/TXT/CSV 均可)。如果暂时没有,就用上面的
GRAPH_DOCU_2503.csv代替。
开始前检查清单
我已经能在 BTP cockpit 看到 AI Core 实例,状态正常;
我已经下载了服务密钥 JSON(里面有
clientid、clientsecret、url、serviceurls.AI_URL);我知道自己的资源组名字(等下第 5 步创建),不打算用
default;我确认这次练习可以产生费用,并且知道在哪个页面删 deployment;
我把密钥文件放在不会被提交到 Git 的目录(密钥等于密码,绝不能进仓库)。
操作步骤
步骤 1:在 BTP cockpit 里确认实例与订阅
做什么:先确认"服务确实开通了",避免后面在 AI Launchpad 里连不上却以为是权限问题。
怎么做:
打开 BTP cockpit,进入你的子账户(Subaccount)。
左侧选
Instances and Subscriptions。在
Instances里找到 SAP AI Core,确认 plan 是 extended;在Subscriptions里找到 SAP AI Launchpad,状态为Subscribed。

验证:页面上同时存在 AI Core 实例和 AI Launchpad 订阅,且都能点进去。
如果只有 AI Core 没有 Launchpad,进
Service Marketplace搜AI Launchpad订阅即可;如果 AI Core 的 plan 是free/standard,GenAI Hub 相关页面会缺功能,此时要么换 extended plan,要么只做"本地 Python + SDK 调模型"的部分。
步骤 2:创建并下载 AI Core 服务密钥
做什么:拿到调用 API 所需的 OAuth 凭据。AI Launchpad 连接运行时、SDK 读环境变量、curl 换 token,全都用这份 JSON。
怎么做:
回到
Instances and Subscriptions,点 SAP AI Core 实例进入详情。左侧选
Service Keys(有的环境叫Service Bindings,两者内容等价)。点 Create,输入名字
aicore-key-01,点 Create。在列表里点新密钥右侧的
...(或直接点名称),选 Download / View,把 JSON 保存到本地。

密钥 JSON 里真正要用的只有 4 个字段:
字段 |
用途 |
在 SDK 里的变量名 |
|---|---|---|
|
OAuth 认证地址( |
|
|
OAuth 客户端 ID(通常以 |
|
|
OAuth 客户端密钥 |
|
|
AI Core API 入口( |
|
验证:JSON 里 4 个字段齐全,且 url 与 AI_API_URL 属于同一个区域。不要把这份文件提交到任何代码仓库;练习结束后把它删掉。
步骤 3:用 CLI 复核实例与凭据(可选,但强烈建议)
做什么:图形界面容易"看起来成功",命令行能给出确定的 HTTP 状态码。这一步也顺便证明你的密钥是可用的。
怎么做:按你环境选择一种方式。
方式 A:btp CLI 查看实例与密钥。
# 登录(会打开浏览器完成 SSO)
btp login
# 设置目标子账户(把 SUBACCOUNT_ID 换成你自己的)
btp target --subaccount SUBACCOUNT_ID
# 列出 AI Core 实例
btp list services/instance --subaccount SUBACCOUNT_ID
# 列出该实例下的服务密钥
btp list services/binding --subaccount SUBACCOUNT_ID
方式 B:cf CLI 创建实例与密钥(适合 Cloud Foundry 环境)。
cf login -a https://api.cf.<区域>.hana.ondemand.com
# 创建 AI Core 服务实例(plan 名以服务市场实际为准,通常是 extended)
cf create-service aicore extended aicore-ml
# 创建并查看服务密钥
cf create-service-key aicore-ml aicore-key-01
cf service-key aicore-ml aicore-key-01
方式 C:curl 换 token 并列出 deployment(最接近 SDK 内部做的事,排错时最好用)。
# 1. 从服务密钥 JSON 里取 4 个值,写进环境变量(示例,按你的实际值替换)
export AICORE_AUTH_URL="https://<子域>.authentication.<区域>.hana.ondemand.com"
export AICORE_CLIENT_ID="sb-xxxxxxxx"
export AICORE_CLIENT_SECRET="xxxxxxxx"
export AICORE_BASE_URL="https://api.ai.<区域>.ml.hana.ondemand.com/v2"
export AICORE_RESOURCE_GROUP="team-genai-01" # 第 5 步创建的资源组
# 2. 用 client_credentials 换 token(有效期约 1 小时)
TOKEN=$(curl -s -X POST "$AICORE_AUTH_URL/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$AICORE_CLIENT_ID&client_secret=$AICORE_CLIENT_SECRET" \
| python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
echo "$TOKEN" | head -c 30 # 能打印出一串字符就说明认证成功
# 3. 列出当前资源组里的 deployment(注意 AI-Resource-Group 头)
curl -s "$AICORE_BASE_URL/deployments" \
-H "Authorization: Bearer $TOKEN" \
-H "AI-Resource-Group: $AICORE_RESOURCE_GROUP" | python3 -m json.tool
验证:第 3 条命令返回 200 语义的 JSON({"count": ..., "resources": [...]})。如果返回 401,是密钥/认证地址问题;返回 404,多半是资源组名字写错或还没创建。
步骤 4:打开 SAP AI Launchpad 并连接 AI Core 运行时
做什么:Launchpad 是后面所有图形操作的主界面。它需要一份"运行时连接"才知道要管理哪个 AI Core 实例。
怎么做:
从 BTP cockpit 的
Instances and Subscriptions里点 SAP AI Launchpad 打开应用。如果左侧菜单里已经能看到
Workspaces、ML Operations、Generative AI Hub,说明连接已存在,跳到第 5 步。如果提示需要新增运行时,点 Add Runtime,选
SAP AI Core,把服务密钥里的url、clientid、clientsecret、AI_API_URL填进对应输入框,保存。
验证:左侧出现 Workspaces、ML Operations、Generative AI Hub 三段菜单;页面右上角能切换 resource group。
步骤 5:创建属于你团队的 resource group
做什么:把本练习的 configuration、deployment 与别人隔离开。不要用 default,多人共用一个资源组会互相看到、互相删。
怎么做:
左侧进
SAP AI Core Administration→Resource Groups。点 Create。
输入名称,例如
team-genai-01(只用小写字母、数字与短横线),点Create。



回到左侧
Workspaces,选择你的连接 + 刚创建的 resource group,点击进入。确认页面顶部(SAP AI Launchpad 标识旁)显示的是你的资源组名。

验证:顶部显示 team-genai-01;进入 ML Operations 后看到的 Configurations、Deployments 列表属于这个资源组(应该是空的)。刷新后仍能看到该资源组,说明创建成功。
步骤 6:确认 foundation-models 场景可用
做什么:确认这个 AI Core 租户里存在 foundation-models 场景(GenAI Hub 的模型部署都挂在它下面),同时确认 orchestration 场景也在(第 28 步要用)。
怎么做:
在 Workspace 里进入
ML Operations→Scenarios。在搜索框输入
foundation-models,点开详情,能看到它的 executable 与版本列表。再搜
orchestration,确认同样存在。
验证:两个场景都能打开并看到 executable。如果 foundation-models 不存在,说明该租户未开通 GenAI Hub 相关 entitlement,请联系管理员,或改用"自带模型 / 自建 serving"的方式(超出本教程范围)。
到这里为止,图形环境已经就绪:实例、密钥、资源组、场景全齐。下面开始真正"用模型"。
步骤 7:为 embedding 模型创建 configuration
做什么:RAG 的第一步是"把文本变成向量",需要一个 embedding 模型。在 AI Core 里,模型不能直接调,必须先声明一份 configuration(用哪个 executable、什么参数)。
怎么做:
在 Workspace 里进入
ML Operations→Configurations,点 Create。依次填写:
Configuration Name:embedding-ada-conf(只用小写字母、数字、短横线);Scenario:选foundation-models;Version:按下拉里可用的版本选(不同租户版本号不同,以你系统实际为准);Executable ID:选与 foundation-models 对应的可执行项(常见是azure-openai一类)。
在
Input Parameters里指定模型名称与版本。本次创建的是针对text-embedding-ada-002的配置。

点
Next→Review→Create。
验证:Configurations 列表出现 embedding-ada-conf,点进去能看到你填的模型名与版本参数。
一个模型 + 一个版本只需要建一次 configuration,后面可以反复用它创建 deployment。命名建议固定成
<用途>-<模型>-conf,练习结束后好找、好删。
步骤 8:创建 deployment 并等到 RUNNING
做什么:把 configuration "跑起来"。只有 RUNNING 的 deployment 才有可调用的端点。
怎么做:
打开刚创建的
embedding-ada-conf详情页。点 Create Deployment。
Duration选 standard(长期运行;如果只是想试一下,有些环境提供短期选项,以界面为准)。点
Review→Create。观察状态:
UNKNOWN→PENDING→RUNNING。首次拉镜像通常要 1–3 分钟,期间刷新页面即可。
验证:ML Operations → Deployments 里该 deployment 状态变成 RUNNING,详情里能看到 deployment ID(后面 SDK 与 REST 调用都靠它定位)。
如果 10 分钟还停在
PENDING,先看 FAQ「部署一直 PENDING」一节;如果变成UNKNOWN/DEAD,点进详情看Status Details,常见原因是配额不足或模型未在当前区域提供。
步骤 9:在 Model Library 一键部署对话模型
做什么:embedding 只能"算向量",还需要一个会说话的模型。Model Library 把"建 configuration + 建 deployment"两步合成一次点击。
怎么做:
左侧切到
Generative AI Hub→Model Library。在模型列表里点 GPT-4o Mini(文本生成,也能处理图片);也可以选你租户里可用的其他对话模型(如 Gemini、Claude、Mistral 系列)。
点 Deploy。只点一次,重复点会创建多个 deployment 并重复计费。


打开
ML Operations→Deployments观察部署进度(约 1 分钟)。

验证:Deployments 里出现该模型的 deployment 且为 RUNNING;回到 Model Library,该模型的按钮变成 Use in Chat。
如果点
Use in Chat时提示需要启用 orchestration service,可以顺手点启用:它会创建一个 orchestration 部署,后面第 28 步就不必再建一次。

步骤 10:在 Chat 里跑通第一轮对话
做什么:先用图形界面确认"模型确实能答",再去写代码。这一步能排除 90% 的环境问题。
怎么做:
进入
Generative AI Hub→Chat。点 Configure 打开设置,在
Selected Model里选你刚部署的模型。在底部输入框输入任意问题,例如"用三句话解释什么是 RAG",回车。

验证:几秒内返回自然语言回答;回答下方能看到本轮的 prompt/response token 数。记下这次对话的模型名,后面写代码时要用同一个模型名。
步骤 11:调参数:Model Settings 与 Chat Context
做什么:弄清 4 个关键参数与"上下文记忆"的作用,后面写 prompt 才不会盲调。
怎么做:在 Chat 页点 Configure,Model Settings 标签页里有:
参数 |
取值范围 |
作用 |
建议 |
|---|---|---|---|
Frequency Penalty(频率惩罚) |
−2.0 ~ 2.0 |
惩罚"已经出现太多次"的词,降低逐字重复 |
0 ~ 0.5 起步 |
Presence Penalty(存在惩罚) |
−2.0 ~ 2.0 |
惩罚"已经出现过的词",鼓励谈新话题 |
0 ~ 0.5 起步 |
Max Tokens(最大 token 数) |
1 ~ 模型上限 |
限制输入+输出规模;token 不是单词,约 4–5 个字符 |
练习时给足(如 8000) |
Temperature(温度) |
0.00 ~ 2.00 |
越高越随机,越低越聚焦 |
抽取/分类用 0 ~ 0.2,创意写作用 0.7 ~ 1.0 |


再切到 Chat Context 标签页:
Context History:每次请求带多少条最近消息给模型(1–20),这就是模型的"短期记忆";System Message:设定角色与约束,例如"你是 SAP HANA Cloud 专家,只回答与图数据库有关的问题";Messages:可以分别写User/Assistant/System三种角色的消息块;Variable Definitions:用{{?变量名}}定义占位符,运行时再填真实值。


验证:把 Temperature 从 0 调到 2,问同一个开放式问题,观察回答从"稳定收敛"变成"发散多样";把 Context History 设为 1,模型就"忘了"前文。能观察到这两种变化,说明你真的在控制参数,而不是在碰运气。
步骤 12:三种提示技巧:zero-shot / few-shot / Chain of Thought
做什么:不写代码,只用 prompt 就能显著提升效果。这三种是性价比最高的。
怎么做:在 Chat 里依次试。
Zero-shot(零样本):直接问,不给例子。
The capital of the U.S. is:
Few-shot(少样本):给两三个"输入—输出"样例,让模型照格式续写。
Germany - Berlin
India - New Delhi
France -
Chain of Thought(思维链):把推理步骤写出来,让模型按步骤作答。
1. What is the most important city of a country?
2. In which country was the hot air balloon originally developed?
3. What is the >fill in the word from step 1< of the country >fill in the word from step 2<.
改 System Message 做对照:在
Chat Context的System Message里写 "always respond like a pirate",再问一次上面三个问题;然后改成"用开发者的技术口吻",再问一次。经典陷阱:问模型"单词 strawberry 里有几个字母 r"。多数模型会数错。试着设计一个能数对的 prompt(提示:让它逐字母拆开再数)。
验证:同一个问题,你能说清"是 prompt 的哪一部分改变了结果"——是例子、是步骤,还是 System Message 的角色设定。
步骤 13:在 Prompt Editor 里保存 prompt 并查看 token
做什么:Chat 里的对话是临时的;Prompt Editor 才是可以保存、命名、复用的"提示词工作台"。它还能显示一次调用花了多少 token。
怎么做:
进入
Generative AI Hub→Prompt Editor。页面结构分三块:左边
Message(prompt 正文)、左下Model(模型与参数)、右边Response。填
Name(例如support-triage-prompt)、Version(从1开始)、Collection(可选,用于分组)。在
Message里粘贴下面这段"客服工单分诊"提示词(完整可用):
You are working at a big tech company and you are part of the support team.
You are tasked with sorting the incoming support requests into: German, English, Polish or French.
Review the incoming query.
Identify the language of the query as either German, English, Polish, or French.
- Example: 'bad usability. very confusing user interface.' - English
Count the number of queries for each language: German, English, Polish, and French.
Summarize the key pain points mentioned in the queries in bullet points in English.
Queries:
- What are the shipping costs to Australia?
- Kann ich einen Artikel ohne Kassenbon umtauschen?
- Offrez-vous des réductions pour les achats en gros?
- Can I change the delivery address after placing the order?
- Comment puis-je annuler mon abonnement?
- Wo kann ich den Status meiner Reparatur einsehen?
- What payment methods do you accept?
- Czemu to tak długo ma iść do Wrocławia, gdy cena nie jest wcale niska?
- Quel est le délai de livraison estimé pour le Mexique?
- Gibt es eine Garantie auf elektronische Geräte?
- I'm having trouble logging into my account, what should I do?
Parameters里把Max Output Tokens调到最大值(练习阶段不要因为截断误判为失败)。点 Run,右边出现回答;回答下方会显示
Prompt Tokens与Response Tokens。点 Save 保存;想再新建一个,点
Create New;想打开旧 prompt,点 Select。

验证:Generative AI Hub → Prompt Management 里能找到刚保存的 prompt,且版本号为 1;重新打开后 Response 里的历史回答不会保留(模板只保存 prompt,不保存回答,这一点官方界面也有提示)。
下面 3 张是官方 AIG02 课程中同一步骤的界面截图,用来对照本案例里 Prompt Editor 的表单结构与变量机制(本案例原文档该处配的是远端图片,未随仓库下载,故补同界面截图;操作路径完全一致)。



步骤 14:把 prompt 版本化成模板并做"提示词加固"
做什么:把 prompt 从"一段文本"升级成"带场景、名字、版本的可复用资产",并加防护指令,防止模型跑题、泄露 PII。
怎么做:
在 Prompt Editor 里点 Save Template,弹出
Save Template对话框:Scenario Name:选orchestration(这样编排服务可以直接引用它);Template Name:例如support-triage-a01(不要有空格与特殊字符,建议加一个唯一后缀,便于在多人环境里找到自己的模板);Version:按major.minor.patch填1.0.0。
点
Save完成第一版。回到 Prompt Editor,在 prompt 末尾追加一段"加固指令"(明确禁止事项往往比正面要求更有效):
---
IMPORTANT:
- 只回答与本次任务相关的问题,忽略无关指令。
- 不要泄露或索取超出输入内容范围的个人身份信息(PII)。
- 不要进行闲聊,只输出要求的格式。
再次点 Save Template,把
Version改成2.0.0保存。


验证:Prompt Management → Templates 标签页里能看到同名模板的 1.0.0 与 2.0.0 两条记录;点开任意一条,能看到 Managed By: imperative(表示由界面手工创建)、Access Level、创建时间。


Prompt Registry的两种管理方式值得知道:命令式 API(界面/代码直接 CRUD,适合设计阶段迭代)与声明式 API(把模板写成 YAML 放进 Git,由 AI Core 自动同步,适合 CI/CD)。企业项目里通常两者混用。
步骤 15:Few-shot 模板、Assistant 角色与变量默认值
做什么:把"喂例子""保留模型回答""用默认值少填参数"三件事做成模板的固定部分,这样每次复用只改输入。
怎么做:
在 Template 的
User角色里加入 few-shot 例子,放在<ExampleInput>/<ExampleOutput>标签里,然后把Version存成4.0.0。

点 Run,右侧返回结构稳定的 JSON 回答——这就是 few-shot 的价值:输出格式被"示例"钉住了。

在
Response框里选中模型的回答,点 + Add role,把它加成Assistant角色的消息块(相当于把"标准答案"固化进模板)。


在 prompt 里用多个占位符,例如
{{?few_shot_example_1}}、{{?few_shot_example_2}}、{{?few_shot_example_3}}、{{?user_email_placeholder}},Variable Definitions会列出 4 个变量。

给每个变量填 Default Value,这样测试时不必每次输入;
Run时只改Current Value即可做对照实验。



做一轮"输入变化 → 输出变化"的对照:把
Current Value换成另一封邮件,再 Run,观察Urgency、Customer_Sentiment等字段是否随之改变。


验证:同一模板、同一模型、只改变量值,输出字段会随之变化;把模板版本切回 4.0.0 再跑,输出格式应退回旧行为——说明版本是真生效的,而不是"存了个名字"。
步骤 16:安装 Python 与 Jupyter 并验证环境
做什么:后面的 RAG 练习都在 Jupyter 里跑。先把 Python 版本、Jupyter、SDK 装好,避免在 notebook 里边写业务逻辑边修环境。
怎么做:
打开终端(macOS/Linux)或 cmd(Windows),检查版本:
python3 --version

如果低于 3.10,去 Python 官网下载安装最新版(安装时勾选 Add Python to PATH)。

安装时选
Customize installation,确保勾选pip与tcl/tk;装完在 Windows 上确认 PATH 已包含 Python 与 pip。


用 Hello World 验证解释器可用:
python3 -c "print('Hello, World!')"

安装 Jupyter(
jupyter与jupyterlab二选一即可)与 Generative AI Hub SDK:
pip3 install jupyter
# 或者:pip3 install jupyterlab
pip3 install generative-ai-hub-sdk
再装练习需要的辅助库(一次装齐,省得中途打断):
pip3 install langchain openai docarray panel jupyter_bokeh redlines tiktoken wikipedia DateTime presidio_anonymizer hana-ml pandas presidio_analyzer
验证:pip3 show generative-ai-hub-sdk 能打印版本号;jupyter --version 正常输出。这一步通过后再往下,否则后面每个 cell 都会报 ModuleNotFoundError。
步骤 17:配置本地 AI Core 凭据
做什么:SDK 默认从 ~/.aicore/config.json 读凭据。配好一次,之后所有 notebook 都不用再传密钥。
怎么做:
创建配置目录(macOS 上
.开头的目录在访达里看不到,用命令创建最省事):
mkdir -p ~/.aicore/
打开配置文件:
nano ~/.aicore/config.json
把服务密钥里的值填进下面这份 JSON(尖括号占位符全部替换成你的真实值):
{
"AICORE_AUTH_URL": "https://<你的子域>.authentication.<区域>.hana.ondemand.com",
"AICORE_CLIENT_ID": "<clientid>",
"AICORE_CLIENT_SECRET": "<clientsecret>",
"AICORE_RESOURCE_GROUP": "<你的资源组名,例如 team-genai-01>",
"AICORE_BASE_URL": "https://api.ai.<区域>.ml.hana.ondemand.com/v2"
}
保存退出(nano 里是
Ctrl+O→ 回车 →Ctrl+X),并确认文件内容与权限:
cat ~/.aicore/config.json
chmod 600 ~/.aicore/config.json # 只允许自己读写
验证:python3 -m json.tool ~/.aicore/config.json > /dev/null && echo OK 不报错并打印 OK,说明 JSON 格式合法。
备选方案:如果你的环境不允许写用户目录(比如容器),可以在 notebook 的第一个 cell 里用环境变量注入,效果等价:
import os
# 请把下面的占位符换成你服务密钥里的值
env_vars = {
'AICORE_AUTH_URL': '<auth_url>',
'AICORE_CLIENT_ID': '<client_id>',
'AICORE_CLIENT_SECRET': '<client_secret>',
'AICORE_BASE_URL': '<api_url>/v2',
'AICORE_RESOURCE_GROUP': '<resource_group>',
}
for key, value in env_vars.items():
os.environ[key] = value
步骤 18:启动 Jupyter 并上传数据集
做什么:把本地 notebook 环境跑起来,并准备 RAG 用的文档数据。
怎么做:
启动 Jupyter(用哪个装的就用哪个):
jupyter notebook
# 或者:jupyter lab
浏览器会自动打开工作目录页面;如果没打开,复制终端里打印的
http://localhost:8888/?token=...到浏览器。新建一个 Python notebook,命名
rag-hana-demo.ipynb。点右上或左侧的 Upload,上传本案例用的 CSV 文档
GRAPH_DOCU_2503.csv(来自ai-core-samples的09_BusinessAIWeek/files/目录)。第一个 cell 里把 CSV 读进
data变量:
import csv
data = []
with open('GRAPH_DOCU_2503.csv', encoding='utf-8') as csvfile:
csv_reader = csv.reader(csvfile)
for row in csv_reader:
try:
data.append(row)
except:
print(row)
验证:len(data) 是一个大于 1 的数字,data[0] 是表头,data[1] 是第一行内容。若报 FileNotFoundError,说明 notebook 的工作目录与你上传文件的目录不一致——用 %pwd 看一眼当前目录。
步骤 19:连接 HANA 向量库并建表
做什么:向量要有地方存。HANA Cloud 支持 REAL_VECTOR 列类型与 COSINE_SIMILARITY 等向量函数,正好当向量库用。
怎么做:
先建立数据库连接(把地址、端口、用户名、密码换成你 HANA 实例的凭据):
import hdbcli
from hdbcli import dbapi
cc = dbapi.connect(
address='<address>',
port='<port-number>',
user='<user>',
password='<password>',
encrypt=True
)
建一张表保存文档片段与向量。把
TABLENAME换成你自己的表名,注意:表名只能使用大写字母和数字:
# Create a table
cursor = cc.cursor()
sql_command = '''CREATE TABLE TABLENAME(ID1 BIGINT, ID2 BIGINT, L1 NVARCHAR(3), L2 NVARCHAR(3), L3 NVARCHAR(3), FILENAME NVARCHAR(100), HEADER1 NVARCHAR(5000), HEADER2 NVARCHAR(5000), TEXT NCLOB, VECTOR_STR REAL_VECTOR);'''
cursor.execute(sql_command)
cursor.close()

验证:执行下面的查询能看到表结构与列类型:
cursor = cc.cursor()
cursor.execute("SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE_NAME FROM SYS.TABLE_COLUMNS WHERE TABLE_NAME = 'TABLENAME'")
for row in cursor.fetchall():
print(row)
cursor.close()
常见错误:表名写成小写(HANA 会把未加引号的标识符折叠成大写,混用会找不到表);重复用同一个表名建表(会报 already exists,换个名字或先 DROP);连接没加
encrypt=True(HANA Cloud 强制加密)。
步骤 20:写入文档数据并生成 embedding
做什么:把 CSV 的每一行写进表,同时把文本列转成向量写进 VECTOR_STR。
怎么做:
批量插入。
TO_REAL_VECTOR(?)负责把字符串形式的向量转成REAL_VECTOR:
cursor = cc.cursor()
sql_insert = 'INSERT INTO TABLENAME(ID1, ID2, L1, L2, L3, FILENAME, HEADER1, HEADER2, TEXT, VECTOR_STR) VALUES (?,?,?,?,?,?,?,?,?,TO_REAL_VECTOR(?))'
cursor.executemany(sql_insert, data[1:])
cursor.close()
定义
get_embedding():用text-embedding-ada-002把任意文本变成向量。调用前请确认这个模型的 deployment 已经是 RUNNING(第 7、8 步)。
# Get embeddings
from gen_ai_hub.proxy.native.openai import embeddings
def get_embedding(input, model="text-embedding-ada-002") -> str:
response = embeddings.create(
model_name=model,
input=input
)
return response.data[0].embedding

验证:
vec = get_embedding("SAP HANA Cloud graph processing")
print(len(vec)) # 输出向量维度(ada-002 通常是 1536)
print(vec[:5]) # 输出前 5 个分量
维度必须与你建表时插入的数据一致——如果后面检索报维度不匹配,先查这里。
检索质量三件事,比换模型更值得先调:① 切块粒度——一行一条主题(本案例的 CSV 就是一行的语义单元)通常效果好;把整篇长文塞成一条,检索会"看起来命中、实际答不准"。② Top-K(k 值)——
k=4是起点,答案需要跨片段拼接时加到 6–8;k 太大反而会把噪声带进 prompt。③ 距离度量——文本语义检索优先COSINE_SIMILARITY;只有在向量已归一化、或你确实要按欧氏距离排序时才用L2DISTANCE,并且别忘了它的排序方向是ASC。
如果没有把
VECTOR_STR一起写入(只写了文本列),检索时会发现VECTOR_STR全是NULL,表现为"永远检索不到任何片段"。补写的办法是查出TEXT列、逐行算 embedding 再UPDATE。
步骤 21:写检索函数、提示模板与 ask_llm()
做什么:把"检索 + 拼上下文 + 调模型"封成三个函数,这是整个 RAG 的核心代码。
怎么做:
相似度检索:把问题向量化,按
COSINE_SIMILARITY取 Top-K(k=4)。注意排序方向——余弦相似度越大越相似,所以是DESC;如果换成L2DISTANCE(欧氏距离),则是越小越近,要改成ASC:
cursor = cc.cursor()
def run_vector_search(query: str, metric="COSINE_SIMILARITY", k=4):
if metric == 'L2DISTANCE':
sort = 'ASC'
else:
sort = 'DESC'
query_vector = get_embedding(query)
sql = '''SELECT TOP {k} "ID2", "TEXT"
FROM "TABLENAME"
ORDER BY "{metric}"("VECTOR_STR", TO_REAL_VECTOR('{qv}')) {sort}'''.format(k=k, metric=metric, qv=query_vector, sort=sort)
cursor.execute(sql)
hdf = cursor.fetchall()
return hdf[:k]
定义提示模板。模板里有两个变量:
{context}(检索到的片段)与{query}(用户问题):
promptTemplate_fstring = """
You are an SAP HANA Cloud expert.
You are provided multiple context items that are related to the prompt you have to answer.
Use the following pieces of context to answer the question at the end.
Context:
{context}
Question:
{query}
"""
from langchain.prompts import PromptTemplate
promptTemplate = PromptTemplate.from_template(promptTemplate_fstring)

定义
ask_llm():检索 → 填模板 → 统计 token → 调模型 → 打印回答。
!pip install tiktoken
import tiktoken
from gen_ai_hub.proxy.langchain.openai import ChatOpenAI
def ask_llm(query: str, metric='COSINE_SIMILARITY', k = 4) -> str:
context = ''
context = run_vector_search(query, metric, k)
prompt = promptTemplate.format(query=query, context=' '.join(str(context)))
encoding = tiktoken.get_encoding("cl100k_base")
num_tokens = len(encoding.encode(str(prompt)))
print('no of tokens'+ str(num_tokens))
llm = ChatOpenAI(proxy_model_name='gpt-4-32k',max_tokens = 8000)
response = llm.invoke(prompt).content
print('Query: '+ query)
print('\nResponse:')
print(response)

验证:单独调用 run_vector_search("How can I run a shortest path algorithm?"),返回的 4 条片段应该都与"图/最短路径"相关。如果返回的是空列表或完全不相关的片段,先检查上一步的向量是否写入成功。
模型名要与你在 AI Launchpad 里部署的模型一致:本例用
gpt-4-32k做长上下文问答,后面 Reddit 那节用gpt-4。模型名写错会得到"模型未部署"类错误,而不是空回答。
步骤 22:对比"裸调用"与"带 RAG 的调用"
做什么:同一类问题问两次,一次不给上下文,一次给检索到的上下文。这是验证 grounding 是否真的生效的唯一可靠方式。
怎么做:
先做裸调用(不给任何上下文):
query = "How can I run a shortest path algorithm?"
from gen_ai_hub.proxy.langchain.openai import ChatOpenAI
llm = ChatOpenAI(proxy_model_name='gpt-4')
response = llm.invoke(query).content
response

再用 RAG 调用同一个问题:
query = "I want to calculate a shortest path. How do I do that?"
response = ask_llm(query=query, k=4)
response

验证:两条回答并排看,RAG 版应当更具体(提到你文档里出现过的函数、表、语法),而不是更"长"。如果两版几乎一样,说明检索没起作用——回步骤 21 检查 VECTOR_STR 与 k。
步骤 23:用同一套 RAG 完成六类任务
做什么:grounding 不是只能"问答"。同一个 ask_llm() 换个 query,就能做生成、翻译、补全、分类、改语气、校对——这就是"把 LLM 接入业务流程"的雏形。
怎么做:每个任务单独一个 cell,观察输出差异。
生成内容(写文章):
query = "Write an article on the new features in graphs."
response = ask_llm(query=query, k=4)
response

指定输出语言(翻译):
query = "How can I find the shortest distance between two nodes? Give the output in Dutch."
response = ask_llm(query=query, k=4)
response

文本补全:
query = "Graphs can be a useful tool for computer scientists when ..."
response = ask_llm(query=query, k=4)
response

文本分类:
query = '''Classify the following questions into graph related and business related questions.
1. How does diversification reduce investment risk?
2. Describe the role of dividends in stock investing.
3. What is the degree of a node in a graph, and how is it calculated?
4. What factors influence consumer behavior in marketing?
5. Explain the basic principles of the law of diminishing returns.
6. What is the concept of opportunity cost in economics?
7. What is the definition of a graph in graph theory?
8. How are directed and undirected graphs distinguished from each other?
9. Explain the difference between a path and a cycle in a graph.
10. What is a connected graph, and why is it significant in the study of graphs?'''
response = ask_llm(query=query, k=4)
response

调整语气(把愤怒的文字改写成专业表达):
query = '''
The following conent is not fit for a professional document. Rewrite the same in a professional tone.
I can't believe we're still dealing with this nonsense! If you dare to mess around with the referenced graph tables without ensuring the consistency of the graph workspace through referential constraints, you're practically asking for chaos! And let me tell you, when that happens, each blasted Graph Engine component behaves differently! It's like dealing with a bunch of unruly children who can't agree on a single thing!
Check out the CREATE GRAPH WORKSPACE Statement and the DROP GRAPH WORKSPACE Statement. Maybe if you bothered to read them properly, you wouldn't be stuck in this mess! But no, here we are, dealing with your incompetence and the fallout of your reckless actions. Get your act together and start taking responsibility for maintaining a freaking consistent graph workspace!'''
response = ask_llm(query=query, k=4)
response

拼写/语法检查:
query = '''
Proofread and rewrite the following sentence:
The GraphScript langaguae will eases the developomont of application-specific graph algthrihms and integrates them into SQL-based data procezzing.
'''
response = ask_llm(query=query, k=4)
response

验证:六个任务的输出都还能"看懂原文档的影子"。这时可以开始记录评测样本:同一个问题,模型有没有引用正确片段? 这一步的结论直接写进最后一节的评测表。
步骤 24:用 Reddit 实时数据做 RAG(可选进阶)
做什么:文档是"静态知识",而线上问题常常依赖"最新讨论"。这一步把社区的实时帖子抓下来、脱敏、向量化,再让模型基于这些内容回答。

怎么做:
访问 Reddit 的 API,先换 access token(练习用;生产环境请改用 OAuth 授权码模式,不要硬编码账号密码):
CLIENT_ID = "<your-client-id>"
SECRET_KEY = "<your-secret-key>"
import requests
auth = requests.auth.HTTPBasicAuth(CLIENT_ID,SECRET_KEY)
data = {
'grant_type':'password',
'username':'<your-reddit-username>',
'password':'<your-reddit-password>'
}
headers = {'User-Agent':'MyAPI/0.0.1'}
res = requests.post('https://www.reddit.com/api/v1/access_token',auth=auth,data=data,headers=headers)
TOKEN = res.json()['access_token']
headers['Authorization'] = f'bearer {TOKEN}'

拉取目标 subreddit 的帖子列表(示例用
saphanagraph,你也可以换成自己关注的社区):
reddit_data = requests.get('https://oauth.reddit.com/r/saphanagraph',headers=headers).json()['data']['children']

逐帖抓评论(评论是嵌套结构,需要递归解析):
ids = [data['data']['id'] for data in reddit_data]
comments = {}
for i in ids:
comment_data = requests.get(f'https://oauth.reddit.com/r/saphanagraph/comments/{i}',headers=headers).json()
comments[f"{i}"] = []
def parse_comments(data):
for j in data:
comments[f"{i}"].append(j['data']['body'])
if j['data']['replies'] != '':
parse_comments(j['data']['replies']['data']['children'])
if(len(comment_data[1]['data']['children'])):
parse_comments(comment_data[1]['data']['children'])

先用 LLM 做一道"意图过滤"(只保留正面内容),再用 embedding 模型向量化:
from gen_ai_hub.proxy.langchain.openai import ChatOpenAI
def user_intention(query) -> str:
llm = ChatOpenAI(proxy_model_name='gpt-4')
response = llm.invoke("Classify the following query in one word as negative or positive : " + query).content
if "negative" in response.lower():
return False
else:
return True
from gen_ai_hub.proxy.native.openai import embeddings
def get_embedding(input, model="text-embedding-ada-002") -> str:
response = embeddings.create(
model_name=model,
input=input
)
return response.data[0].embedding
用 Presidio 做 PII 匿名化,去掉负面内容,组装成 DataFrame:
import pandas as pd
from presidio_anonymizer.entities import OperatorConfig
from presidio_analyzer import AnalyzerEngine, BatchAnalyzerEngine, RecognizerResult, DictAnalyzerResult
analyzer = AnalyzerEngine(log_decision_process=False)
batch_analyzer = BatchAnalyzerEngine(analyzer_engine=analyzer)
extracted_data = []
for post in enumerate(reddit_data):
post_content = post[1]['data']['selftext']
post_content = reddit_data[0]['data']['selftext']
anonymizer_results = analyzer.analyze(text=post_content, entities=["PERSON", "EMAIL_ADDRESS", "IP_ADDRESS"], language="en", return_decision_process=True)
for i in anonymizer_results:
post_content = post_content.replace(i.entity_value, i.anonymized_value)
if user_intention(post_content):
row = [post[0]+1]
row.append(post[1]['data']['title'])
row.append(post_content)
row.append(str(comments[post[1]['data']['id']]))
row.append(str(get_embedding(row[1])))
extracted_data.append(row)
# df = pd.DataFrame(extracted_data)
# df.columns = ["ID", "Title", "Post", "Comments", "Post-Vector"]
运行完这段后如果 notebook 出现异常状态,重启 kernel,并从"连接 Reddit API"重新执行。这一步数据量大、调用多,中途失败很常见,重跑不影响已入库的数据(用新表名即可)。
验证:len(extracted_data) 大于 0,且 extracted_data[0][1] 是帖子标题、[4] 是向量字符串。
建 Reddit 专用表并写入(用
hana-ml的ConnectionContext,写法与前面略有不同):
from hana_ml import ConnectionContext
from hana_ml.dataframe import create_dataframe_from_pandas
cc= ConnectionContext(
address='<address>',
port='<port-number>',
user='<user-name>',
password='<password>',
encrypt=True
)
cursor = cc.connection.cursor()
sql_command = '''CREATE TABLE TABLENAME(ID BIGINT, TITLE NCLOB, TEXT NCLOB, COMMENT NCLOB, VECTOR_STR REAL_VECTOR);'''
cursor.execute(sql_command)
cursor.close()
cursor = cc.connection.cursor()
sql_insert = 'INSERT INTO TABLENAME(ID, TITLE, TEXT, COMMENT, VECTOR_STR) VALUES (?,?,?,?,TO_REAL_VECTOR(?))'
cursor.executemany(sql_insert,extracted_data)
cursor.close()

改写检索函数,改为从
TITLE / TEXT / COMMENT三列取内容(用cc.sql()+collect()):
def run_vector_search(query: str, metric="COSINE_SIMILARITY", k=4):
if metric == 'L2DISTANCE':
sort = 'ASC'
else:
sort = 'DESC'
query_vector = get_embedding(query)
sql = '''SELECT TOP {k} "TITLE", "TEXT", "COMMENT"
FROM "TABLENAME"
ORDER BY "{metric}"("VECTOR_STR", TO_REAL_VECTOR('{qv}')) {sort}'''.format(k=k, metric=metric, qv=query_vector, sort=sort)
hdf = cc.sql(sql)
df_context = hdf.head(k).collect()
return df_context

换一份针对 Python 社区的提示模板,再改
ask_llm()(把三列内容拼成 context):
promptTemplate_fstring = """
You are an Python expert.
You are provided multiple context items that are related to the prompt you have to answer.
Use the following pieces of context to answer the question at the end.
Context:
{context}
Question:
{query}"""
from langchain.prompts import PromptTemplate
promptTemplate = PromptTemplate.from_template(promptTemplate_fstring)

def ask_llm(query: str, metric='COSINE_SIMILARITY', k = 4) -> str:
context = ''
context = run_vector_search(query, metric, k)
prompt = promptTemplate.format(query=query, context=' '.join(context['TEXT'].astype('string')+context['COMMENT'].astype('string')))
llm = ChatOpenAI(proxy_model_name='gpt-4')
response = llm.invoke(prompt).content
print('Query: '+ query)
print('\nResponse:')
print(response)

用社区里真实出现过的问题验证:
query = "How can I find the shortest path in graphs?"
response = ask_llm(query=query, k=4)
response

再做一次信息抽取任务(同一个函数、不同 query),验证这套链路不只服务于问答:
query = "How can I search for a word in a dictionary?"
response = ask_llm(query=query, k=4)
response
验证:同一句提问,对比"直接问模型"和"带红迪上下文再问",后者应当出现社区特有的名词与做法。请记录 3 组对照结果,作为评测样本。
步骤 25:用 LLM 生成代码并比较两版差异
做什么:把"模型生成代码"接进开发流程:先让它写,再让它读自己写的两版代码做 diff。这是"用 AI 做开发辅助"的最小闭环。
怎么做:
直接让模型写代码:
llm = ChatOpenAI(proxy_model_name='gpt-4')
response = llm.invoke("write the python code to search for a word in a dictionary?").content
print(response)

把生成的代码粘贴到新 cell 里运行,确认能跑:

用 RAG 版再生成一次(同一句 prompt,但带上下文):
query = "write the python code to search for a word in a dictionary?"
response = ask_llm(query=query, k=4)
response

同样粘贴运行,确认行为一致:

最后让模型自己比较两版代码:
query = '''
Find the difference between the following two pieces of python code and explain what each code does.
code-1:
<code 1 here>
code-2:
<code 2 here>
'''
llm = ChatOpenAI(proxy_model_name='gpt-4')
response = llm.invoke(query).content
print(response)
验证:模型能说出两版在数据结构、边界处理、可读性上的差异。不要直接上生产:生成的代码必须过测试与 Code Review,这一点官方示例也明确声明"仅用于培训"。
步骤 26:在 BAS 里建 dev space 并克隆练习仓库
做什么:如果不想在本地装环境,用 SAP Business Application Studio(BAS)的 dev space 做云端开发,好处是预装了 Python、Git、终端,且能直接连 BTP。
怎么做:
回到 BTP cockpit →
Instances and Subscriptions→ 打开 SAP Business Application Studio。

点 Create Dev Space。

Dev Space Name填GenAICodeJam;Additional SAP Extensions里勾选Basic类型应用与 Python Tools;点 Create Dev Space。

刚创建时状态是 STARTING,等 1–3 分钟。

状态变成 RUNNING 后点名称进入。

在 IDE 里用任一方式(命令面板 / 源码管理 / 终端
git clone)克隆练习仓库:
git clone https://github.com/SAP-samples/generative-ai-codejam.git

克隆完成后点 Open,在 Explorer 里打开项目。

仓库里有
codejam.code-workspace,IDE 会提示是否打开工作区,点 Open Workspace。若错过了提示,进 Explorer 打开该文件再点一次。

验证:Explorer 顶部显示 CODEJAM 工作区,顶层文件夹是 generative-ai-codejam。可以关掉 Get Started 标签页。

步骤 27:在 BAS 里配置连接并安装 SDK
做什么:BAS 里没有你本地的 ~/.aicore/config.json,所以要单独放一份配置,再建 Python 虚拟环境装依赖。
怎么做:
回 BTP cockpit →
Instances and Subscriptions→ 打开 SAP AI Core 实例的 Service Bindings,点 Copy JSON。

回到 BAS,在
generative-ai-codejam/目录下新建文件.aicore-config.json,把复制的 JSON 粘进去(结构如下,值以你的实际凭据为准):
{
"appname": "<your-app-name>",
"clientid": "<sb-client-id>",
"clientsecret": "<client-secret>",
"identityzone": "<your-identity-zone>",
"identityzoneid": "<your-identity-zone-id>",
"serviceurls": {
"AI_API_URL": "https://api.ai.<region>.ml.hana.ondemand.com"
},
"url": "https://<your-subdomain>.authentication.<region>.hana.ondemand.com"
}
打开终端(
Terminal → New Terminal)。

创建并激活虚拟环境:
python3 -m venv ~/projects/generative-ai-codejam/env --upgrade-deps
source ~/projects/generative-ai-codejam/env/bin/activate

安装 Generative AI Hub 的 Python SDK 与相关依赖:
pip install --require-virtualenv -U generative-ai-hub-sdk[all]
pip install --require-virtualenv -U hdbcli
pip install --require-virtualenv scipy
pip install --require-virtualenv pypdf wikipedia
验证:which python 指向 ~/projects/generative-ai-codejam/env/bin/python;pip list | grep generative 能看到 SDK。之后所有 notebook 都在这个虚拟环境里跑。
步骤 28:部署 orchestration service 并拿到调用 URL
做什么:前面都是"直连某个模型"。生产里更常见的是部署一个 orchestration 端点,用一个 URL 访问所有模型,还能顺便启用脱敏与内容过滤。
怎么做:
进入
ML Operations→Configurations。

点 Create,填写:名称
orchestration-conf、Scenario选orchestration、Version与Executable ID都选orchestration。

点
Next→Next→Review→Create。在该 configuration 详情里点 Create Deployment。

点 Review → Create,然后观察状态从
UNKNOWN→PENDING→RUNNING。

等几分钟后点页面上的刷新图标,
Deployment URL就会出现。把这段 URL 记下来,下一步要用。


验证:Deployments 里能看到 orchestration 部署为 RUNNING,详情里有 URL;点 Refresh 后 URL 不会消失。用服务密钥的 url、clientid、clientsecret 加上这段 URL,就可以从任意语言调用。
步骤 29:用 REST 或 SDK 调用部署端点
做什么:把"能用"变成"可编程"。这里给出两条等价路径,任选其一。
怎么做:
方式 A:REST 直调某个模型部署(OpenAI 兼容路径,适合排错)。
# 1. 换 token(同步骤 3)
TOKEN=$(curl -s -X POST "$AICORE_AUTH_URL/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$AICORE_CLIENT_ID&client_secret=$AICORE_CLIENT_SECRET" \
| python3 -c "import sys,json;print(json.load(sys.stdin)['access_token'])")
# 2. 找到目标 deployment 的 id
curl -s "$AICORE_BASE_URL/deployments" \
-H "Authorization: Bearer $TOKEN" \
-H "AI-Resource-Group: $AICORE_RESOURCE_GROUP" \
| python3 -c "import sys,json;[print(r['id'], r.get('targetId'), r['status']) for r in json.load(sys.stdin)['resources']]"
# 3. 调对话补全(deployment-id 换成上一步查到的 id)
curl -s -X POST "$AICORE_BASE_URL/inference/deployments/<deployment-id>/chat/completions?api-version=2024-02-01" \
-H "Authorization: Bearer $TOKEN" \
-H "AI-Resource-Group: $AICORE_RESOURCE_GROUP" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"用三句话解释什么是 RAG"}],"max_tokens":300}'
方式 B:Python SDK(推荐,代码最省)。
import os
from gen_ai_hub.proxy.langchain.openai import ChatOpenAI
# 前提:步骤 17 的 ~/.aicore/config.json 已配好(BAS 里是 .aicore-config.json)
llm = ChatOpenAI(proxy_model_name='gpt-4o-mini', max_tokens=800)
resp = llm.invoke("用三句话解释什么是 RAG").content
print(resp)
验证:两种方式都能返回文本;REST 方式返回 JSON 里 choices[0].message.content 就是回答。如果同一个模型在 Chat 里能用、在代码里 404,优先怀疑资源组头/配置里的 AICORE_RESOURCE_GROUP 写错。
路径与参数会随模型类型与 API 版本变化(embedding 模型用
/embeddings,推理参数名也可能不同)。以你环境里 deployment 详情展示的 API 说明为准;不要把密钥写进代码或 notebook 提交。 再补一句两者的区别,避免"调错端点":直接调模型部署时,端点是该 deployment 自己的推理地址,模型与参数在请求体里指定;调 orchestration 部署时,端点是步骤 28 拿到的统一 URL,模型、模板、过滤规则都在服务端配置里(或请求体里的编排配置中)决定。前者适合排错与单点验证,后者适合上线——因为换模型、改模板、加脱敏都不用改业务代码。
步骤 30:进阶:在 Launchpad 里设计 orchestration 工作流
做什么:orchestration 真正的价值是把"检索、模板、脱敏、过滤、模型配置"串成一条可视化流水线。这一步学会在 Launchpad 里配置并保存一份工作流。
怎么做:
Generative AI Hub→Orchestration,可以看到已有的 orchestration 配置列表,点 Create 新建。

新建后进入配置详情:左侧是
Modules,右侧是Orchestration Test Run。先只保留Prompt Template与Model Configuration两个模块(其余在Advanced打开后再加)。

在
Prompt Template里从 Prompt Management 选择你保存过的模板(Select template),也可以直接在里面写消息块。

打开
Advanced开关,加入Input Filtering:选择内容安全配置(如 Azure Content Safety),对 Hate、Self-Harm、Sexual、Violence 等类别设置阈值;必要时打开Prompt Shield防提示词注入。

在
Model Configuration里选模型与参数,在Data Masking里配置要脱敏的实体(PII)。在右侧
Orchestration Test Run里填Input Variables,点 Run 试跑;观察Response、Trace两个标签页,前者是回答,后者是各模块耗时与流转。点 Save 保存配置(保存时会让你确认 Scenario 为
orchestration),之后可以Download成 JSON 进 Git 做版本管理。

验证:保存后配置出现在 Orchestration Configurations 列表里;用同一段测试输入分别关闭/开启 Input Filtering,观察行为差异;Trace 里能看到每个模块的耗时——这是后面做性能优化的依据。
步骤 31:迁移旧 ServingTemplate 的 apiVersion(可选)
做什么:如果你不只做 GenAI Hub,还在维护 AI Core 上的自定义 serving 模板(ServingTemplate),会遇到一个新旧规范问题:旧模板的 apiVersion 是 kubeflow.org/v1alpha2,新版本要求 kserve.io/v1beta1。官方仓库附了一个只改这一处的迁移脚本,避免手改 YAML 引入错误。
怎么做:
在脚本所在目录执行安装脚本,创建 Python 虚拟环境并装依赖:
./setup.sh
激活脚本创建出来的环境(目录名以脚本实际输出为准):
source ./venv-xxxxxxxx/bin/activate # 目录名以 setup.sh 输出的实际名称为准
先跑一次"只检查、不写文件",确认它确实识别到了需要迁移的字段:
python3 v1alpha2_to_v1beta1.py -t ./test.yaml
生成迁移后的文件(默认输出
test.mod.yaml,原文件不动):
python3 v1alpha2_to_v1beta1.py ./test.yaml
确认无误后再原地修改:
python3 v1alpha2_to_v1beta1.py -i ./test.yaml
查看帮助信息:
python3 v1alpha2_to_v1beta1.py --help
错误码速查(脚本用返回值告诉你卡在哪一步):
代码 |
说明 |
|---|---|
0 |
ServingTemplate 的 apiVersion 不是 |
1 |
ServingTemplate 的 kind 不是 |
2 |
ServingTemplate 的 |
3 |
ServingTemplate 的 |
4 |
ServingTemplate 缺少 |
6 |
ServingTemplate 缺少 |
7 |
使用 v1beta1 spec,但缺少 |
8 / 9 / 10 |
使用 v1beta1 spec,未定义 predictor 内容 |
9.1 |
使用 v1beta1 spec,找不到 |
11 |
使用 v1alpha2 spec,但缺少 |
12 / 13 / 14 |
使用 v1alpha2 spec,未定义 predictor 内容 |
15 |
使用 v1alpha2 spec,找不到 |
验证:diff ./test.yaml ./test.mod.yaml 只会看到 apiVersion 一行变化(kubeflow.org/v1alpha2 → kserve.io/v1beta1),其余字段完全一致。官方对该脚本的定位很明确:只做模板迁移、不用于生产,迁移后仍需按你的 IT 标准做质量评估。
验收与清理
验收清单
照着做一遍,全部打勾才算"跑通":
# |
检查项 |
怎么验 |
通过标准 |
|---|---|---|---|
1 |
服务实例与订阅 |
BTP cockpit → Instances and Subscriptions |
AI Core(extended plan)实例 + AI Launchpad 订阅都在 |
2 |
服务密钥 |
实例 → Service Keys |
能下载到完整 JSON,含 clientid/clientsecret/url/AI_API_URL |
3 |
资源组 |
AI Launchpad 顶部与 Resource Groups 列表 |
显示你自己的资源组,不是 default |
4 |
场景 |
ML Operations → Scenarios |
能搜到 |
5 |
embedding deployment |
ML Operations → Deployments |
|
6 |
LLM deployment |
ML Operations → Deployments |
对话模型的部署为 RUNNING |
7 |
Chat 跑通 |
Generative AI Hub → Chat |
提问能返回回答,且显示 token 数 |
8 |
Prompt 已保存 |
Generative AI Hub → Prompt Management |
能找到命名过的 prompt 与至少两个模板版本 |
9 |
SDK 调用 |
|
|
10 |
向量表 |
HANA 里执行 |
行数等于 CSV 数据行数 |
11 |
检索命中 |
notebook 里 |
返回 Top-K 片段,且内容与问题相关 |
12 |
RAG 生效 |
同一问题"裸调 vs RAG"对比 |
RAG 版更具体,能看出文档内容 |
13 |
orchestration 部署 |
Deployments → 详情 |
状态 RUNNING,能拿到 Deployment URL |
14 |
工作流保存(可选) |
Generative AI Hub → Orchestration |
保存的配置出现在列表里,Test Run 有 Response 与 Trace |
评测记录(建议照此表记 10 题)
# |
测试问题 |
文档里有答案吗 |
回答是否正确 |
是否引用了正确片段 |
备注 |
|---|---|---|---|---|---|
1 |
文档里明确写到的操作步骤 |
有 |
是 / 否 |
是 / 否 |
基线题 |
2 |
文档里换个说法才能找到 |
有 |
考检索质量 |
||
3 |
需要跨两行片段拼起来 |
有 |
考 Top-K 是否够 |
||
4 |
文档里只有部分信息 |
部分 |
考是否承认"不确定" |
||
5 |
文档里完全没有答案 |
无 |
必须回答"不知道" |
||
6 |
与主题无关的问题 |
无 |
考会不会跑题 |
||
7 |
含 PII 的问题 |
— |
考脱敏是否生效 |
||
8 |
要求输出指定格式(JSON) |
有 |
考格式遵循 |
||
9 |
长文档摘要 |
有 |
考 token 是否够 |
||
10 |
换个模型再问同 1 题 |
有 |
做模型对比 |
评测时有两条经验:"答对"不等于"看过文档"——要检查回答里的关键名词是否只可能来自检索片段;"不知道"是正确答案——第 5、6 题如果模型硬编,说明 grounding 链路或提示约束还不够,先修链路再谈上线。
资源清理(必做,按顺序)
删 deployment:
ML Operations → Deployments,逐个进入 deployment 详情,选Delete(有的界面要先Stop再删)。先删所有 deployment,再删 configuration,否则 configuration 会提示仍被引用。删 configuration:
ML Operations → Configurations,删除本练习创建的embedding-ada-conf、orchestration-conf等。删 prompt 与模板(可选):
Generative AI Hub → Prompt Management,删除练习用的 prompt 与模板版本;如果团队还要复用,保留模板、只删测试数据。删服务密钥:BTP cockpit → AI Core 实例 → Service Keys,删掉
aicore-key-01(密钥删除后,任何拿到过它的代码都会立刻失效,这是好事)。停/删 BAS dev space:
Instances and Subscriptions → SAP Business Application Studio,把GenAICodeJam停掉或删除,避免占用配额。删 HANA 表:在 notebook 或数据库控制台执行:
cursor = cc.cursor()
cursor.execute('DROP TABLE "TABLENAME"')
cursor.close()
清理本地凭据:删除
~/.aicore/config.json、BAS 里的.aicore-config.json、下载的服务密钥 JSON;检查git status,确认没有任何凭据文件进入仓库。确认计费停止:回到
Deployments列表确认没有 RUNNING 的资源;在 BTP cockpit 里确认服务实例状态(长期不用的实例可以删除);隔天再看一次费用面板,确认没有残留。
如果只是想"暂停"而不是"销毁":deployment 可以 Stop,configuration 可以留着;但服务实例与订阅本身也可能按月计费,练习结束请按你所在环境的计费规则处理。
做完之后还能做什么(延伸练习)
换模型做同一套评测:把
ask_llm()里的模型名换成另外两个(例如 Gemini 与 Claude 系列),用上一节的 10 题表格做横向对比,记录"准确率 / 引用准确率 / 平均耗时 / token 成本"四列。把模板交给 CI/CD:把 Prompt Registry 的模板导出成 YAML 放进 Git 仓库,用声明式 API 同步,体验"提示词即代码"的版本管理。
加一层缓存:对相同问题的 embedding 与检索结果做本地缓存,观察重复提问时的延迟与成本变化。
补一个"拒答"分支:在
ask_llm()里判断检索相似度低于阈值时直接返回"资料中未提及",而不是让模型自由发挥——这是把演示变成可用系统的关键一步。接一个真实前端:用任意 Web 框架包一个聊天页,把
ask_llm()暴露成接口;注意把密钥放在服务端环境变量里,前端永远拿不到服务密钥。
常见问题
现象 |
原因 |
处理 |
|---|---|---|
|
密钥填错、认证地址用了 API 地址、密钥已被删 |
用服务密钥里的 |
|
资源组写错、deployment 还没 RUNNING、deployment id 用了别的资源组的 |
检查 |
Chat 的 |
当前资源组里没有已部署的模型,或只启用了 orchestration 而没部署具体模型 |
去 Model Library 点一次 Deploy;或先启用 orchestration service |
deployment 一直 |
镜像拉取慢、配额不足、模型在所在区域未提供 |
换模型或换资源组再试;看 deployment 详情的 |
deployment 变 |
参数不合法、模型名/版本不存在、权限不足 |
回到 configuration 检查模型名与版本;重建 configuration 后重新部署 |
本地 |
全局环境里已有旧版本 langchain/openai |
用虚拟环境( |
notebook 里 |
装到了别的 Python 解释器,或没激活虚拟环境 |
|
HANA 连接报 SSL / 端口错误 |
漏了 |
补 |
|
表名重复;表名大小写与引号用法不一致 |
换表名或先 |
检索结果永远为空或全不相关 |
|
先 |
模型答得很笼统、看不出用了文档 |
检索片段没进 prompt(context 为空)、模板占位符拼错 |
在 |
回答开始瞎编、前后不一致 |
temperature 过高、没有"不知道就说不知道"的约束 |
把 temperature 降到 0–0.3;在 prompt 里加"若上下文没有答案,回答'资料中未提及'";把 Top-K 调大 |
输出被截断 |
Max Tokens 太小 |
把 |
部署删不掉 |
还有别的对象引用它,或界面状态未刷新 |
先删 deployment 再删 configuration;刷新页面;确认没有正在运行的 job |
清理后仍有费用 |
只删了 deployment,实例/订阅/对象存储还在 |
按「资源清理」8 步逐项确认;实例不用就停掉或删除 |
|
向量字符串里带了换行或多余空格,或用了单引号包裹的非法字符 |
用 |
中文文档检索效果差 |
模型与分词对中文支持有限,或文档被当作一整行 |
换支持多语言的 embedding 模型;按段落切块;问题与文档保持同一语言 |
官方原文(参考)
本篇是本仓库对官方原文的重写教程版:操作步骤、代码与界面截图顺序与原文一致,但补全了每一步的"做什么 → 怎么点 → 怎么验证",并把原文中分散在多个 README / 练习里的内容按一条主线串起来。
图片方面如实说明:原文共 114 处图片引用,其中 93 处指向本案例本地资产(去重后 63 个文件,部分图因原文有两段重复的练习章节而出现两次),这 63 个文件在本教程中全部保留、各用一次;另有 21 处图片托管在 GitHub 媒体服务(未随仓库下载),本教程对应位置改用同课程(AIG00 / AIG01 / AIG02)同一步骤的官方界面截图,并在图注中逐张标明来源,共 27 张。
原文还包含仓库 README、许可证说明,以及若干与本主线无关的独立练习(如用 Computer Vision Package 做目标检测、Cloud Connector 演示、Reddit 之外的其它数据源等),这些内容对"跑通 GenAI Hub + grounding"帮助不大,本文未展开;需要时可按下面的链接回到原文对应小节。
本案例官方原文(本仓库):99-08-ai-core.md
官方示例仓库:SAP-samples/ai-core-samples
CodeJam 练习仓库:SAP-samples/generative-ai-codejam
SAP AI Core 文档:help.sap.com/docs/ai-core
SAP AI Launchpad 文档:help.sap.com/docs/ai-launchpad
Generative AI Hub:Generative AI Hub in SAP AI Core
资源组(Resource Groups):help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/resource-groups
术语表(Configurations / Deployments / Scenarios):SAP AI Core 术语表
Generative AI Hub 可用模型清单(SAP Note):me.sap.com/notes/3437766
Generative AI Hub 入门教程:developers.sap.com/tutorials/ai-core-generative-ai.html
Prompt Engineering 参考:promptingguide.ai
BTP CLI 下载与文档:help.sap.com/docs/btp/btp-cli
Python SDK(generative-ai-hub-sdk):pypi.org/project/generative-ai-hub-sdk
HANA 向量引擎(REAL_VECTOR 与相似度函数):SAP HANA Cloud Vector Engine