08 · SAP AI Core / Generative AI Hub:完整图文教程

目标:在 SAP AI Core 上跑通第一个大模型调用,把提示词做成可版本化的模板,再做一次基于自有文档的 grounding(检索增强生成)。 预计:3–5 小时 | 难度:中高 | 前置课程:AIG00–AIG03、HAML01–HAML04

你会做出什么

一条从零到能演示的完整链路:

  1. BTP 子账户里的 SAP AI Core 服务实例(extended plan)+ SAP AI Launchpad 订阅;

  2. AI Launchpad 里属于你自己团队的 resource group;

  3. 在 Model Library 一键部署一个对话模型,在 ML Operations 里为 embedding 模型创建 configuration + deployment;

  4. 用 Chat 和 Prompt Editor 把提示词调好,并存成带版本号的提示模板;

  5. 在本地(或 BAS)用 Python + Generative AI Hub SDK 通过 orchestration service 的部署 URL 调用模型;

  6. 把一份 CSV 业务文档向量化写进 SAP HANA Cloud 的向量表,用 COSINE_SIMILARITY 检索 + 提示模板做 grounding,让模型"基于你的文档"回答;

  7. 最后按清理清单把 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 题的小评测记录(正确率 / 是否引用到正确文档片段);

  • 一张清理完成截图清单,证明没有遗留计费资源。

官方课程中 Generative AI Hub 的全貌:左侧是部署后即可调用的基础模型(GPT-4o Mini、Claude、Gemini、Mistral、Nova 等),中间是 SAP AI Launchpad 的 Prompt Editor,右侧是业务应用里的 Chat(来自 AIG00 官方课程同一步截图)

读法说明:本教程按操作顺序编排,前一步的"验证"没通过就不要进入下一步。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 在组内隔离

team-genai-01

scenario(场景)

一类 AI 任务的集合

foundation-models(基础模型)、orchestration(编排)

executable(可执行项)

场景里真正能跑的实现模板

azure-openai、orchestration 等

configuration(配置)

"用哪个 executable + 哪些参数"的配方

embedding-ada-conf

deployment(部署)

把 configuration 跑起来,得到一个可调用的端点

llm-proxy-run-01

一次调用的链路可以画成这样(文字版):

你的代码 / 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 → Input Filtering → Model Configuration → Output Filtering,对上层暴露统一的 API(来自 AIG00 官方课程同一步截图)

这张图值得记住,因为它解释了为什么企业项目最终都会用 orchestration:

  • Grounding(检索):从数据仓库/向量库取相关片段;

  • Templating(模板):把用户输入填进版本化的提示模板;

  • Data Masking(脱敏):把 PII(身份证、邮箱、IP 等)在发给模型前遮掉;

  • Input / Output Filtering(内容过滤):拦截有害内容;

  • Model Configuration(模型配置):指定模型与 temperature、max tokens 等参数。

grounding 的调用链(RAG)

"模型能回答"和"模型答对"之间差的就是 grounding。RAG(Retrieval-Augmented Generation,检索增强生成)把外部知识在提问时塞进 prompt,而不是把知识训练进模型。

RAG 的三个动作:Retrieval(检索相关片段)→ Augmentation(拼进 prompt,增强上下文)→ Generation(模型基于上下文生成回答)(来自 AIG01 官方课程同一步截图)

本教程用到的具体链路是:

阶段

做什么

用到的组件

① 入库

读 CSV 文档,按行拆成主题片段

Python csv

② 向量化

调 text-embedding-ada-002 把每段文本变成向量

Generative AI Hub SDK embeddings.create

③ 存储

写进 HANA 表,向量列类型 REAL_VECTOR

SAP HANA Cloud + hdbcli / hana-ml

④ 检索

把问题也向量化,按 COSINE_SIMILARITY 取 Top-K

SQL:ORDER BY COSINE_SIMILARITY(...) DESC

⑤ 生成

把 Top-K 片段填进提示模板,调用 LLM

ChatOpenAI(proxy_model_name=...)

一句话记住各环节的职责: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 步会建)。

  • 命令行工具(二选一即可):

    • btp CLI(SAP BTP 命令行),用于查服务实例/密钥;

    • cf CLI(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 里连不上却以为是权限问题。

怎么做:

  1. 打开 BTP cockpit,进入你的子账户(Subaccount)。

  2. 左侧选 Instances and Subscriptions。

  3. 在 Instances 里找到 SAP AI Core,确认 plan 是 extended;在 Subscriptions 里找到 SAP AI Launchpad,状态为 Subscribed。

BTP cockpit 的 Instances and Subscriptions 页面:同时能看到 SAP AI Core 实例与 SAP AI Launchpad 订阅

验证:页面上同时存在 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。

怎么做:

  1. 回到 Instances and Subscriptions,点 SAP AI Core 实例进入详情。

  2. 左侧选 Service Keys(有的环境叫 Service Bindings,两者内容等价)。

  3. 点 Create,输入名字 aicore-key-01,点 Create。

  4. 在列表里点新密钥右侧的 ...(或直接点名称),选 Download / View,把 JSON 保存到本地。

SAP AI Core 服务密钥详情页:能看到 clientid、clientsecret、url、identityzone、serviceurls 等字段

密钥 JSON 里真正要用的只有 4 个字段:

字段

用途

在 SDK 里的变量名

url

OAuth 认证地址(https://<子域>.authentication.<区域>.hana.ondemand.com)

AICORE_AUTH_URL

clientid

OAuth 客户端 ID(通常以 sb- 开头)

AICORE_CLIENT_ID

clientsecret

OAuth 客户端密钥

AICORE_CLIENT_SECRET

serviceurls.AI_API_URL

AI Core API 入口(https://api.ai.<区域>.ml.hana.ondemand.com)

AICORE_BASE_URL(要补 /v2)

验证: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 实例。

怎么做:

  1. 从 BTP cockpit 的 Instances and Subscriptions 里点 SAP AI Launchpad 打开应用。

  2. 如果左侧菜单里已经能看到 Workspaces、ML Operations、Generative AI Hub,说明连接已存在,跳到第 5 步。

  3. 如果提示需要新增运行时,点 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,多人共用一个资源组会互相看到、互相删。

怎么做:

  1. 左侧进 SAP AI Core Administration → Resource Groups。

  2. 点 Create。

  3. 输入名称,例如 team-genai-01(只用小写字母、数字与短横线),点 Create。

AI Launchpad 的 Resource Groups 列表页:右上角 Create 按钮用于新建资源组

新建 resource group 的对话框:输入名称后创建;名称不要用 default

创建完成后资源组会出现在列表里;如果没看到,用浏览器刷新按钮刷新页面

  1. 回到左侧 Workspaces,选择你的连接 + 刚创建的 resource group,点击进入。

  2. 确认页面顶部(SAP AI Launchpad 标识旁)显示的是你的资源组名。

进入 Workspace 后,顶部会显示当前 resource group;这里是后续所有操作的"作用域"

验证:顶部显示 team-genai-01;进入 ML Operations 后看到的 Configurations、Deployments 列表属于这个资源组(应该是空的)。刷新后仍能看到该资源组,说明创建成功。

步骤 6:确认 foundation-models 场景可用

做什么:确认这个 AI Core 租户里存在 foundation-models 场景(GenAI Hub 的模型部署都挂在它下面),同时确认 orchestration 场景也在(第 28 步要用)。

怎么做:

  1. 在 Workspace 里进入 ML Operations → Scenarios。

  2. 在搜索框输入 foundation-models,点开详情,能看到它的 executable 与版本列表。

  3. 再搜 orchestration,确认同样存在。

验证:两个场景都能打开并看到 executable。如果 foundation-models 不存在,说明该租户未开通 GenAI Hub 相关 entitlement,请联系管理员,或改用"自带模型 / 自建 serving"的方式(超出本教程范围)。

到这里为止,图形环境已经就绪:实例、密钥、资源组、场景全齐。下面开始真正"用模型"。

步骤 7:为 embedding 模型创建 configuration

做什么:RAG 的第一步是"把文本变成向量",需要一个 embedding 模型。在 AI Core 里,模型不能直接调,必须先声明一份 configuration(用哪个 executable、什么参数)。

怎么做:

  1. 在 Workspace 里进入 ML Operations → Configurations,点 Create。

  2. 依次填写:

    • Configuration Name:embedding-ada-conf(只用小写字母、数字、短横线);

    • Scenario:选 foundation-models;

    • Version:按下拉里可用的版本选(不同租户版本号不同,以你系统实际为准);

    • Executable ID:选与 foundation-models 对应的可执行项(常见是 azure-openai 一类)。

  3. 在 Input Parameters 里指定模型名称与版本。本次创建的是针对 text-embedding-ada-002 的配置。

为 embedding 模型创建 configuration:Name、Scenario、Version、Executable ID 四个必填项,下面填模型名称与版本

  1. 点 Next → Review → Create。

验证:Configurations 列表出现 embedding-ada-conf,点进去能看到你填的模型名与版本参数。

一个模型 + 一个版本只需要建一次 configuration,后面可以反复用它创建 deployment。命名建议固定成 <用途>-<模型>-conf,练习结束后好找、好删。

步骤 8:创建 deployment 并等到 RUNNING

做什么:把 configuration "跑起来"。只有 RUNNING 的 deployment 才有可调用的端点。

怎么做:

  1. 打开刚创建的 embedding-ada-conf 详情页。

  2. 点 Create Deployment。

  3. Duration 选 standard(长期运行;如果只是想试一下,有些环境提供短期选项,以界面为准)。

  4. 点 Review → Create。

  5. 观察状态: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"两步合成一次点击。

怎么做:

  1. 左侧切到 Generative AI Hub → Model Library。

  2. 在模型列表里点 GPT-4o Mini(文本生成,也能处理图片);也可以选你租户里可用的其他对话模型(如 Gemini、Claude、Mistral 系列)。

  3. 点 Deploy。只点一次,重复点会创建多个 deployment 并重复计费。

Generative AI Hub 的 Model Library:按提供方分组列出可部署模型,右侧有 Deploy 按钮

点开某个模型后的详情:能看到模型能力、上下文长度与 Deploy 按钮

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

Deployments 列表:每行一个部署,状态列显示 RUNNING 才算可用

验证:Deployments 里出现该模型的 deployment 且为 RUNNING;回到 Model Library,该模型的按钮变成 Use in Chat。

如果点 Use in Chat 时提示需要启用 orchestration service,可以顺手点启用:它会创建一个 orchestration 部署,后面第 28 步就不必再建一次。

未部署模型时的提示:引导你启用 orchestration service,启用后即可与所有模型对话

步骤 10:在 Chat 里跑通第一轮对话

做什么:先用图形界面确认"模型确实能答",再去写代码。这一步能排除 90% 的环境问题。

怎么做:

  1. 进入 Generative AI Hub → Chat。

  2. 点 Configure 打开设置,在 Selected Model 里选你刚部署的模型。

  3. 在底部输入框输入任意问题,例如"用三句话解释什么是 RAG",回车。

Chat 界面:左侧是会话列表,中间是对话,右上角可切换模型与参数

验证:几秒内返回自然语言回答;回答下方能看到本轮的 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 的 Model Settings:Selected Model + Frequency/Presence Penalty、Max Tokens、Temperature 四个滑杆 + Streaming Response 开关(来自 AIG00 官方课程同一步截图)

Chat 的另一个标签页:Model Settings 与 Chat Context 并列,切过去才能设置上下文记忆

再切到 Chat Context 标签页:

  • Context History:每次请求带多少条最近消息给模型(1–20),这就是模型的"短期记忆";

  • System Message:设定角色与约束,例如"你是 SAP HANA Cloud 专家,只回答与图数据库有关的问题";

  • Messages:可以分别写 User / Assistant / System 三种角色的消息块;

  • Variable Definitions:用 {{?变量名}} 定义占位符,运行时再填真实值。

Chat 的 Chat Context 设置:Context History、Messages(User/Assistant/System 三个角色)、Variable Definitions 占位符(来自 AIG00 官方课程同一步截图)

Chat Context 页的另一块区域:在这里加 System Message 与示例输入输出,等价于手写 few-shot

验证:把 Temperature 从 0 调到 2,问同一个开放式问题,观察回答从"稳定收敛"变成"发散多样";把 Context History 设为 1,模型就"忘了"前文。能观察到这两种变化,说明你真的在控制参数,而不是在碰运气。

步骤 12:三种提示技巧:zero-shot / few-shot / Chain of Thought

做什么:不写代码,只用 prompt 就能显著提升效果。这三种是性价比最高的。

怎么做:在 Chat 里依次试。

  1. Zero-shot(零样本):直接问,不给例子。

The capital of the U.S. is:
  1. Few-shot(少样本):给两三个"输入—输出"样例,让模型照格式续写。

Germany - Berlin
India - New Delhi
France -
  1. 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<.
  1. 改 System Message 做对照:在 Chat Context 的 System Message 里写 "always respond like a pirate",再问一次上面三个问题;然后改成"用开发者的技术口吻",再问一次。

  2. 经典陷阱:问模型"单词 strawberry 里有几个字母 r"。多数模型会数错。试着设计一个能数对的 prompt(提示:让它逐字母拆开再数)。

验证:同一个问题,你能说清"是 prompt 的哪一部分改变了结果"——是例子、是步骤,还是 System Message 的角色设定。

步骤 13:在 Prompt Editor 里保存 prompt 并查看 token

做什么:Chat 里的对话是临时的;Prompt Editor 才是可以保存、命名、复用的"提示词工作台"。它还能显示一次调用花了多少 token。

怎么做:

  1. 进入 Generative AI Hub → Prompt Editor。

  2. 页面结构分三块:左边 Message(prompt 正文)、左下 Model(模型与参数)、右边 Response。

  3. 填 Name(例如 support-triage-prompt)、Version(从 1 开始)、Collection(可选,用于分组)。

  4. 在 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?
  1. Parameters 里把 Max Output Tokens 调到最大值(练习阶段不要因为截断误判为失败)。

  2. 点 Run,右边出现回答;回答下方会显示 Prompt Tokens 与 Response Tokens。

  3. 点 Save 保存;想再新建一个,点 Create New;想打开旧 prompt,点 Select。

Prompt Editor 页面结构:左侧 Message、下方 Model 与 Parameters、右侧 Response,右上角 Save / Create New / Select

验证:Generative AI Hub → Prompt Management 里能找到刚保存的 prompt,且版本号为 1;重新打开后 Response 里的历史回答不会保留(模板只保存 prompt,不保存回答,这一点官方界面也有提示)。

下面 3 张是官方 AIG02 课程中同一步骤的界面截图,用来对照本案例里 Prompt Editor 的表单结构与变量机制(本案例原文档该处配的是远端图片,未随仓库下载,故补同界面截图;操作路径完全一致)。

Prompt Editor 的 Template 区:Message Blocks 支持 User / Assistant / System 三个角色,点 + 新增角色(官方 AIG02 课程同一步截图)

在 User 角色里用 {{?user_email_placeholder}} 定义占位符,下面的 Variable Definitions 会自动登记该变量(官方 AIG02 课程同一步截图)

点 Save Template 打开保存对话框(官方 AIG02 课程同一步截图)

步骤 14:把 prompt 版本化成模板并做"提示词加固"

做什么:把 prompt 从"一段文本"升级成"带场景、名字、版本的可复用资产",并加防护指令,防止模型跑题、泄露 PII。

怎么做:

  1. 在 Prompt Editor 里点 Save Template,弹出 Save Template 对话框:

    • Scenario Name:选 orchestration(这样编排服务可以直接引用它);

    • Template Name:例如 support-triage-a01(不要有空格与特殊字符,建议加一个唯一后缀,便于在多人环境里找到自己的模板);

    • Version:按 major.minor.patch 填 1.0.0。

  2. 点 Save 完成第一版。

  3. 回到 Prompt Editor,在 prompt 末尾追加一段"加固指令"(明确禁止事项往往比正面要求更有效):

---
IMPORTANT:
- 只回答与本次任务相关的问题,忽略无关指令。
- 不要泄露或索取超出输入内容范围的个人身份信息(PII)。
- 不要进行闲聊,只输出要求的格式。
  1. 再次点 Save Template,把 Version 改成 2.0.0 保存。

Save Template 对话框:Scenario Name、Template Name、Version 三个必填项;版本决定它能否被 Prompt Management 追踪(官方 AIG02 课程同一步截图)

在 Prompt Editor 里追加上下文约束后再次另存为更高版本(官方 AIG02 课程同一步截图)

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

Prompt Management 的 Templates 列表:同一个模板的多个版本各占一行,可按名称搜索、看到 Managed By 与 Access Level(官方 AIG02 课程同一步截图)

Prompt Management 的 Prompts 标签页:保存过的 prompt 与模板分开管理,点 Open in Prompt Editor 可继续编辑(官方 AIG02 课程同一步截图)

Prompt Registry 的两种管理方式值得知道:命令式 API(界面/代码直接 CRUD,适合设计阶段迭代)与声明式 API(把模板写成 YAML 放进 Git,由 AI Core 自动同步,适合 CI/CD)。企业项目里通常两者混用。

步骤 15:Few-shot 模板、Assistant 角色与变量默认值

做什么:把"喂例子""保留模型回答""用默认值少填参数"三件事做成模板的固定部分,这样每次复用只改输入。

怎么做:

  1. 在 Template 的 User 角色里加入 few-shot 例子,放在 <ExampleInput> / <ExampleOutput> 标签里,然后把 Version 存成 4.0.0。

保存 few-shot 版本的 Save Template 对话框:把版本推进到 4.0.0(官方 AIG02 课程同一步截图)

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

加了 few-shot 之后运行模板,Response 里返回结构化的 JSON(官方 AIG02 课程同一步截图)

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

在 Response 上点 + Add role,把模型输出固化为 Assistant 角色的消息块(官方 AIG02 课程同一步截图)

再存一个新版本 4.1.0(官方 AIG02 课程同一步截图)

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

Variable Definitions 列出全部占位符(本图为 4 个变量),每个变量都有 Current Value 与 Default Value 两列(官方 AIG02 课程同一步截图)

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

给变量填默认值:左侧是变量名,右侧是默认值文本域(官方 AIG02 课程同一步截图)

运行时只改变量的 Current Value(当前值)、Default Value 保持不动,这样同一模板就能做 A/B 对照(官方 AIG02 课程同一步截图)

Assistant 角色的消息块会渲染在模板里,点 Run 即可带着示例再问一次(官方 AIG02 课程同一步截图)

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

同一模板换输入后,Response 中的字段值随之变化(官方 AIG02 课程同一步截图)

再换一次输入做对照:同样是 5.0.0 版本,回答的 Urgency 从 High 变成 Low,说明变量生效(官方 AIG02 课程同一步截图)

验证:同一模板、同一模型、只改变量值,输出字段会随之变化;把模板版本切回 4.0.0 再跑,输出格式应退回旧行为——说明版本是真生效的,而不是"存了个名字"。

步骤 16:安装 Python 与 Jupyter 并验证环境

做什么:后面的 RAG 练习都在 Jupyter 里跑。先把 Python 版本、Jupyter、SDK 装好,避免在 notebook 里边写业务逻辑边修环境。

怎么做:

  1. 打开终端(macOS/Linux)或 cmd(Windows),检查版本:

python3 --version

终端里执行 python3 --version,输出应为 3.10 或更高

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

Python 官网下载页:选择与你操作系统匹配的安装包

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

Windows 安装选项:勾选 pip、tcl/tk 等组件;「Add Python to PATH」一定要勾上

安装完成后在环境变量里确认 Python 与 pip 的 PATH 已配置(仅 Windows 需要这一步)

  1. 用 Hello World 验证解释器可用:

python3 -c "print('Hello, World!')"

命令行输出 Hello, World!,说明 Python 解释器与 PATH 都正常

  1. 安装 Jupyter(jupyter 与 jupyterlab 二选一即可)与 Generative AI Hub SDK:

pip3 install jupyter
# 或者:pip3 install jupyterlab

pip3 install generative-ai-hub-sdk
  1. 再装练习需要的辅助库(一次装齐,省得中途打断):

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 都不用再传密钥。

怎么做:

  1. 创建配置目录(macOS 上 . 开头的目录在访达里看不到,用命令创建最省事):

mkdir -p ~/.aicore/
  1. 打开配置文件:

nano ~/.aicore/config.json
  1. 把服务密钥里的值填进下面这份 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"
}
  1. 保存退出(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 用的文档数据。

怎么做:

  1. 启动 Jupyter(用哪个装的就用哪个):

jupyter notebook
# 或者:jupyter lab
  1. 浏览器会自动打开工作目录页面;如果没打开,复制终端里打印的 http://localhost:8888/?token=... 到浏览器。

  2. 新建一个 Python notebook,命名 rag-hana-demo.ipynb。

  3. 点右上或左侧的 Upload,上传本案例用的 CSV 文档 GRAPH_DOCU_2503.csv(来自 ai-core-samples 的 09_BusinessAIWeek/files/ 目录)。

  4. 第一个 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 等向量函数,正好当向量库用。

怎么做:

  1. 先建立数据库连接(把地址、端口、用户名、密码换成你 HANA 实例的凭据):

import hdbcli
from hdbcli import dbapi

cc = dbapi.connect(
    address='<address>',
    port='<port-number>',
    user='<user>',
    password='<password>',
    encrypt=True
    )
  1. 建一张表保存文档片段与向量。把 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()

在 Jupyter 里执行 CREATE TABLE 语句:成功时该 cell 不报错,表里多出一个 REAL_VECTOR 列用于存向量

验证:执行下面的查询能看到表结构与列类型:

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。

怎么做:

  1. 批量插入。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()
  1. 定义 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

在 notebook 里调用 get_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 的核心代码。

怎么做:

  1. 相似度检索:把问题向量化,按 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]
  1. 定义提示模板。模板里有两个变量:{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)

在 notebook 里用 PromptTemplate.from_template 生成模板对象:它把 context 与 query 两个占位符固定下来

  1. 定义 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)

ask_llm 的运行输出:先打印 prompt 的 token 数,再打印 Query 与 Response 两段

验证:单独调用 run_vector_search("How can I run a shortest path algorithm?"),返回的 4 条片段应该都与"图/最短路径"相关。如果返回的是空列表或完全不相关的片段,先检查上一步的向量是否写入成功。

模型名要与你在 AI Launchpad 里部署的模型一致:本例用 gpt-4-32k 做长上下文问答,后面 Reddit 那节用 gpt-4。模型名写错会得到"模型未部署"类错误,而不是空回答。

步骤 22:对比"裸调用"与"带 RAG 的调用"

做什么:同一类问题问两次,一次不给上下文,一次给检索到的上下文。这是验证 grounding 是否真的生效的唯一可靠方式。

怎么做:

  1. 先做裸调用(不给任何上下文):

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

裸调用 gpt-4 的回答:泛泛而谈,给的是通用算法步骤,没有落到你的文档内容上

  1. 再用 RAG 调用同一个问题:

query = "I want to calculate a shortest path. How do I do that?"
response = ask_llm(query=query, k=4)
response

带 RAG 的回答:会引用检索到的文档片段,给出与你的数据/系统相关的具体做法

验证:两条回答并排看,RAG 版应当更具体(提到你文档里出现过的函数、表、语法),而不是更"长"。如果两版几乎一样,说明检索没起作用——回步骤 21 检查 VECTOR_STR 与 k。

步骤 23:用同一套 RAG 完成六类任务

做什么:grounding 不是只能"问答"。同一个 ask_llm() 换个 query,就能做生成、翻译、补全、分类、改语气、校对——这就是"把 LLM 接入业务流程"的雏形。

怎么做:每个任务单独一个 cell,观察输出差异。

  1. 生成内容(写文章):

query = "Write an article on the new features in graphs."
response = ask_llm(query=query, k=4)
response

用 RAG 生成一篇关于图数据库新特性的短文,内容会贴合检索到的文档

  1. 指定输出语言(翻译):

query = "How can I find the shortest distance between two nodes? Give the output in Dutch."
response = ask_llm(query=query, k=4)
response

在 prompt 里指定 Dutch,模型改用荷兰语回答,技术内容仍来自检索片段

  1. 文本补全:

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

给半句话让模型续写,输出应当延续同一主题而不是跳到无关内容

  1. 文本分类:

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

让模型把 10 个问题分成 graph related / business related 两类

  1. 调整语气(把愤怒的文字改写成专业表达):

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

改语气任务:输出把原文的抱怨口吻改写成专业书面表达,技术要点保留

  1. 拼写/语法检查:

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(可选进阶)

做什么:文档是"静态知识",而线上问题常常依赖"最新讨论"。这一步把社区的实时帖子抓下来、脱敏、向量化,再让模型基于这些内容回答。

工作流 2 的思路:把社区实时数据接入已有的向量库与 ask_llm 链路,形成"静态文档 + 实时讨论"双数据源

怎么做:

  1. 访问 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}'

换 token 成功后,headers 里带上 Authorization,后续每次请求都复用它

  1. 拉取目标 subreddit 的帖子列表(示例用 saphanagraph,你也可以换成自己关注的社区):

reddit_data = requests.get('https://oauth.reddit.com/r/saphanagraph',headers=headers).json()['data']['children']

拉取到的帖子列表:JSON 里每条都有 id、title、selftext 等字段

  1. 逐帖抓评论(评论是嵌套结构,需要递归解析):

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'])

评论抓取完成:comments 字典里每个帖子 id 对应一串评论正文

  1. 先用 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
  1. 用 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] 是向量字符串。

  1. 建 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()

写入 Reddit 数据到 HANA 向量表:执行完 insert 后表里应有与 extracted_data 相同数量的行

  1. 改写检索函数,改为从 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

改用 hana-ml 的 cc.sql() 执行检索:返回的是 DataFrame,便于后续拼 prompt

  1. 换一份针对 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)

新的提示模板:角色从 HANA 专家换成 Python 专家,变量仍是 context 与 query

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)

改造后的 ask_llm:context 由 TEXT 与 COMMENT 两列拼接,模型换成 gpt-4

  1. 用社区里真实出现过的问题验证:

query = "How can I find the shortest path in graphs?"
response = ask_llm(query=query, k=4)
response

回答里带有 Reddit 讨论中的具体说法,而不是模型自己编的通用建议

  1. 再做一次信息抽取任务(同一个函数、不同 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 做开发辅助"的最小闭环。

怎么做:

  1. 直接让模型写代码:

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)

模型返回的 Python 代码:通常包含函数定义与示例调用

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

运行模型生成的代码,输出应当是"单词在字典中/不在字典中"判断结果

  1. 用 RAG 版再生成一次(同一句 prompt,但带上下文):

query = "write the python code to search for a word in a dictionary?"
response = ask_llm(query=query, k=4)
response

带 RAG 的代码生成:会倾向于使用检索片段里出现过的写法/库

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

运行 RAG 版生成的代码,结果应与上一版等价或更贴合你的系统

  1. 最后让模型自己比较两版代码:

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。

怎么做:

  1. 回到 BTP cockpit → Instances and Subscriptions → 打开 SAP Business Application Studio。

BTP cockpit 里的 SAP Business Application Studio 入口

  1. 点 Create Dev Space。

BAS 的 dev space 列表页:右上角 Create Dev Space

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

创建 dev space:命名并勾选 Python Tools 等扩展

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

dev space 处于 STARTING 状态,属于正常启动过程

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

dev space 变成 RUNNING,点击即可打开 IDE

  1. 在 IDE 里用任一方式(命令面板 / 源码管理 / 终端 git clone)克隆练习仓库:

git clone https://github.com/SAP-samples/generative-ai-codejam.git

BAS 里克隆 Git 仓库:输入仓库 URL 后等待完成

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

克隆完成后在 Explorer 里打开项目

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

打开 workspace 的提示:点 Open Workspace 才会看到完整的项目结构

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

打开后的工作区:根节点是 CODEJAM,下面是 generative-ai-codejam 文件夹

步骤 27:在 BAS 里配置连接并安装 SDK

做什么:BAS 里没有你本地的 ~/.aicore/config.json,所以要单独放一份配置,再建 Python 虚拟环境装依赖。

怎么做:

  1. 回 BTP cockpit → Instances and Subscriptions → 打开 SAP AI Core 实例的 Service Bindings,点 Copy JSON。

BTP cockpit 里的 Service Binding 详情:Copy JSON 会把整份凭据复制到剪贴板

  1. 回到 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"
}
  1. 打开终端(Terminal → New Terminal)。

BAS 里打开终端:菜单里能看到 Terminal,也可以直接用快捷键

  1. 创建并激活虚拟环境:

python3 -m venv ~/projects/generative-ai-codejam/env --upgrade-deps

source ~/projects/generative-ai-codejam/env/bin/activate

虚拟环境激活后,终端提示符前面会出现 (env) 前缀

  1. 安装 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 访问所有模型,还能顺便启用脱敏与内容过滤。

怎么做:

  1. 进入 ML Operations → Configurations。

Configurations 列表:一个配置对应一套"场景+可执行项+参数"

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

创建 orchestration 的 configuration:名称 orchestration-conf,场景与可执行项都选 orchestration

  1. 点 Next → Next → Review → Create。

  2. 在该 configuration 详情里点 Create Deployment。

在 configuration 详情页点 Create Deployment,为它创建部署

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

部署创建向导:确认参数后点 Review 与 Create

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

Deployment 详情里出现 URL:这就是后续调用 orchestration 的入口

Deployments 列表:可以看到所有部署及其状态,orchestration proxy 部署不会真的把所有模型都跑起来

验证: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 里配置并保存一份工作流。

怎么做:

  1. Generative AI Hub → Orchestration,可以看到已有的 orchestration 配置列表,点 Create 新建。

Generative AI Hub 左侧菜单中的 Orchestration,右侧是 Orchestration Configurations 列表与 Create 按钮(官方 AIG02 课程同一步截图)

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

新建 orchestration 配置:左侧 Modules 区可开关模块,右侧 Test Run 用来即时验证(官方 AIG02 课程同一步截图)

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

从 Prompt Management 选择模板:同一个模板的多个版本都会列出(官方 AIG02 课程同一步截图)

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

Input Filtering 模块:按有害类别设置允许的严重级别阈值,并可开启 Prompt Shield(官方 AIG02 课程同一步截图)

  1. 在 Model Configuration 里选模型与参数,在 Data Masking 里配置要脱敏的实体(PII)。

  2. 在右侧 Orchestration Test Run 里填 Input Variables,点 Run 试跑;观察 Response、Trace 两个标签页,前者是回答,后者是各模块耗时与流转。

  3. 点 Save 保存配置(保存时会让你确认 Scenario 为 orchestration),之后可以 Download 成 JSON 进 Git 做版本管理。

保存并在 Orchestration Test Run 中试跑:左侧模块列表、中间模块配置、右侧输入变量与响应(官方 AIG02 课程同一步截图)

验证:保存后配置出现在 Orchestration Configurations 列表里;用同一段测试输入分别关闭/开启 Input Filtering,观察行为差异;Trace 里能看到每个模块的耗时——这是后面做性能优化的依据。

步骤 31:迁移旧 ServingTemplate 的 apiVersion(可选)

做什么:如果你不只做 GenAI Hub,还在维护 AI Core 上的自定义 serving 模板(ServingTemplate),会遇到一个新旧规范问题:旧模板的 apiVersion 是 kubeflow.org/v1alpha2,新版本要求 kserve.io/v1beta1。官方仓库附了一个只改这一处的迁移脚本,避免手改 YAML 引入错误。

怎么做:

  1. 在脚本所在目录执行安装脚本,创建 Python 虚拟环境并装依赖:

./setup.sh
  1. 激活脚本创建出来的环境(目录名以脚本实际输出为准):

source ./venv-xxxxxxxx/bin/activate        # 目录名以 setup.sh 输出的实际名称为准
  1. 先跑一次"只检查、不写文件",确认它确实识别到了需要迁移的字段:

python3 v1alpha2_to_v1beta1.py -t ./test.yaml
  1. 生成迁移后的文件(默认输出 test.mod.yaml,原文件不动):

python3 v1alpha2_to_v1beta1.py ./test.yaml
  1. 确认无误后再原地修改:

python3 v1alpha2_to_v1beta1.py -i ./test.yaml

查看帮助信息:

python3 v1alpha2_to_v1beta1.py --help

错误码速查(脚本用返回值告诉你卡在哪一步):

代码

说明

0

ServingTemplate 的 apiVersion 不是 ai.sap.com/v1alpha1

1

ServingTemplate 的 kind 不是 ServingTemplate

2

ServingTemplate 的 labels 不存在

3

ServingTemplate 的 labels.scenarios.ai.sap.com/id 不存在

4

ServingTemplate 缺少 spec.template

6

ServingTemplate 缺少 spec.template.spec

7

使用 v1beta1 spec,但缺少 spec.template.spec.predictor

8 / 9 / 10

使用 v1beta1 spec,未定义 predictor 内容

9.1

使用 v1beta1 spec,找不到 imagePullSecrets

11

使用 v1alpha2 spec,但缺少 spec.template.spec.default

12 / 13 / 14

使用 v1alpha2 spec,未定义 predictor 内容

15

使用 v1alpha2 spec,找不到 imagePullSecrets

验证: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

能搜到 foundation-models 与 orchestration

5

embedding deployment

ML Operations → Deployments

embedding-ada-conf 的部署为 RUNNING

6

LLM deployment

ML Operations → Deployments

对话模型的部署为 RUNNING

7

Chat 跑通

Generative AI Hub → Chat

提问能返回回答,且显示 token 数

8

Prompt 已保存

Generative AI Hub → Prompt Management

能找到命名过的 prompt 与至少两个模板版本

9

SDK 调用

python3 交互或 notebook

llm.invoke(...) 返回文本,无 401/404

10

向量表

HANA 里执行 SELECT COUNT(*) FROM "TABLENAME"

行数等于 CSV 数据行数

11

检索命中

notebook 里 run_vector_search(问题)

返回 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 链路或提示约束还不够,先修链路再谈上线。

资源清理(必做,按顺序)

  1. 删 deployment:ML Operations → Deployments,逐个进入 deployment 详情,选 Delete(有的界面要先 Stop 再删)。先删所有 deployment,再删 configuration,否则 configuration 会提示仍被引用。

  2. 删 configuration:ML Operations → Configurations,删除本练习创建的 embedding-ada-conf、orchestration-conf 等。

  3. 删 prompt 与模板(可选):Generative AI Hub → Prompt Management,删除练习用的 prompt 与模板版本;如果团队还要复用,保留模板、只删测试数据。

  4. 删服务密钥:BTP cockpit → AI Core 实例 → Service Keys,删掉 aicore-key-01(密钥删除后,任何拿到过它的代码都会立刻失效,这是好事)。

  5. 停/删 BAS dev space:Instances and Subscriptions → SAP Business Application Studio,把 GenAICodeJam 停掉或删除,避免占用配额。

  6. 删 HANA 表:在 notebook 或数据库控制台执行:

cursor = cc.cursor()
cursor.execute('DROP TABLE "TABLENAME"')
cursor.close()
  1. 清理本地凭据:删除 ~/.aicore/config.json、BAS 里的 .aicore-config.json、下载的服务密钥 JSON;检查 git status,确认没有任何凭据文件进入仓库。

  2. 确认计费停止:回到 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() 暴露成接口;注意把密钥放在服务端环境变量里,前端永远拿不到服务密钥。

常见问题

现象

原因

处理

401 Unauthorized / invalid_client

密钥填错、认证地址用了 API 地址、密钥已被删

用服务密钥里的 url 作为 AICORE_AUTH_URL(不是 AI_API_URL);重新下载密钥;确认 clientsecret 没有多余空格

404 Resource not found / deployment not found

资源组写错、deployment 还没 RUNNING、deployment id 用了别的资源组的

检查 AI-Resource-Group 头或 AICORE_RESOURCE_GROUP;在 Deployments 列表确认状态与 id

Chat 的 Selected Model 列表是空的

当前资源组里没有已部署的模型,或只启用了 orchestration 而没部署具体模型

去 Model Library 点一次 Deploy;或先启用 orchestration service

deployment 一直 PENDING,十几分钟不动

镜像拉取慢、配额不足、模型在所在区域未提供

换模型或换资源组再试;看 deployment 详情的 Status Details;确认配额

deployment 变 UNKNOWN / DEAD

参数不合法、模型名/版本不存在、权限不足

回到 configuration 检查模型名与版本;重建 configuration 后重新部署

本地 pip install 报依赖冲突

全局环境里已有旧版本 langchain/openai

用虚拟环境(python3 -m venv .venv && source .venv/bin/activate)隔离后再装

notebook 里 ModuleNotFoundError: gen_ai_hub

装到了别的 Python 解释器,或没激活虚拟环境

which python / pip -V 确认指向同一环境;重装 generative-ai-hub-sdk

HANA 连接报 SSL / 端口错误

漏了 encrypt=True、端口不是 443、IP 未放行

补 encrypt=True;用 443 端口;把出口 IP 加进 HANA Cloud 的允许列表

CREATE TABLE 报 already exists / 查不到刚建的表

表名重复;表名大小写与引号用法不一致

换表名或先 DROP;HANA 会把未加引号的标识符折叠成大写,统一写大写表名

检索结果永远为空或全不相关

VECTOR_STR 没写入、k 太小、排序方向反了、表名占位符没替换

先 SELECT COUNT(*) 看行数;检查 ORDER BY ... DESC(L2 用 ASC);确认 SQL 里的 "TABLENAME" 已替换

模型答得很笼统、看不出用了文档

检索片段没进 prompt(context 为空)、模板占位符拼错

在 ask_llm 里先 print(context[:500]),确认上下文非空再调模型

回答开始瞎编、前后不一致

temperature 过高、没有"不知道就说不知道"的约束

把 temperature 降到 0–0.3;在 prompt 里加"若上下文没有答案,回答'资料中未提及'";把 Top-K 调大

输出被截断

Max Tokens 太小

把 max_tokens 提到 4000–8000(不超过模型上限);长文档先摘要再问

部署删不掉

还有别的对象引用它,或界面状态未刷新

先删 deployment 再删 configuration;刷新页面;确认没有正在运行的 job

清理后仍有费用

只删了 deployment,实例/订阅/对象存储还在

按「资源清理」8 步逐项确认;实例不用就停掉或删除

TO_REAL_VECTOR('[...]') 报语法/格式错误

向量字符串里带了换行或多余空格,或用了单引号包裹的非法字符

用 json.dumps(vec) 或 str(vec) 生成纯数字逗号序列;SQL 里用 TO_REAL_VECTOR(?) 走参数绑定而不是拼字符串

中文文档检索效果差

模型与分词对中文支持有限,或文档被当作一整行

换支持多语言的 embedding 模型;按段落切块;问题与文档保持同一语言

官方原文(参考)

本篇是本仓库对官方原文的重写教程版:操作步骤、代码与界面截图顺序与原文一致,但补全了每一步的"做什么 → 怎么点 → 怎么验证",并把原文中分散在多个 README / 练习里的内容按一条主线串起来。

图片方面如实说明:原文共 114 处图片引用,其中 93 处指向本案例本地资产(去重后 63 个文件,部分图因原文有两段重复的练习章节而出现两次),这 63 个文件在本教程中全部保留、各用一次;另有 21 处图片托管在 GitHub 媒体服务(未随仓库下载),本教程对应位置改用同课程(AIG00 / AIG01 / AIG02)同一步骤的官方界面截图,并在图注中逐张标明来源,共 27 张。

原文还包含仓库 README、许可证说明,以及若干与本主线无关的独立练习(如用 Computer Vision Package 做目标检测、Cloud Connector 演示、Reddit 之外的其它数据源等),这些内容对"跑通 GenAI Hub + grounding"帮助不大,本文未展开;需要时可按下面的链接回到原文对应小节。