alibabacloud-bailian-rag-knowledgebase

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bailian Knowledge Base Retrieval

百炼知识库检索

This Skill provides query and retrieval capabilities for Alibaba Cloud Bailian Knowledge Base, supporting intelligent selection across multiple knowledge bases.
该Skill提供阿里云百炼知识库的查询和检索能力,支持跨多知识库智能选择。

🚀 Initial Setup (Required for First-time Use)

🚀 初始配置(首次使用必需)

1. Install Dependencies

1. 安装依赖

bash
npm install
This will install all dependencies defined in package.json:
  • @alicloud/bailian20231229
    - Bailian Knowledge Base SDK
  • @alicloud/modelstudio20260210
    - Modelstudio Workspace SDK
  • @alicloud/openapi-client
    - OpenAPI Client
bash
npm install
这将安装package.json中定义的所有依赖:
  • @alicloud/bailian20231229
    - 百炼知识库SDK
  • @alicloud/modelstudio20260210
    - Modelstudio工作区SDK
  • @alicloud/openapi-client
    - OpenAPI客户端

2. Configure Alibaba Cloud Credentials

2. 配置阿里云凭证

This tool uses the Alibaba Cloud default credential chain, supporting multiple credential configuration methods (in order of priority):
Method 1: Alibaba Cloud CLI (Recommended)
bash
undefined
本工具使用阿里云默认凭证链,支持多种凭证配置方式(优先级从高到低):
方法1:阿里云CLI(推荐)
bash
undefined

Configure credentials using Alibaba Cloud CLI

使用阿里云CLI配置凭证

aliyun configure

**Method 2: Configuration File**
Alibaba Cloud SDK will automatically read credential configuration from `~/.aliyun/config.json` or `~/.acs/credentials`.

**Note:** 
- For first-time use, if credentials are not detected, guide users to configure using `aliyun configure`
- Do not explicitly handle user's AK/SK credentials, rely on Alibaba Cloud default credential chain
aliyun configure

**方法2:配置文件**
阿里云SDK会自动从 `~/.aliyun/config.json` 或 `~/.acs/credentials` 读取凭证配置。

**注意:** 
- 首次使用如果检测不到凭证,引导用户使用 `aliyun configure` 进行配置
- 不要显式处理用户的AK/SK凭证,依赖阿里云默认凭证链实现

3. Important Prerequisite: Activate Bailian and Knowledge Base Service

3. 重要前置条件:开通百炼和知识库服务

Before using this skill, you must first activate the knowledge base service in the Alibaba Cloud Bailian console!
  1. Visit Bailian Knowledge Base page
  2. Click the "Activate Now" button
  3. Confirm activation and wait for the service to take effect (usually 1-2 minutes)
使用本Skill前,必须先在阿里云百炼控制台开通知识库服务!
  1. 访问百炼知识库页面
  2. 点击 "立即开通" 按钮
  3. 确认开通并等待服务生效(通常需要1-2分钟)

4. Important Prerequisite: Guide Users to Grant Permissions in Alibaba Cloud Access Control and Bailian

4. 重要前置条件:引导用户在阿里云访问控制和百炼中授予权限

Before using this skill, you must grant the following permissions to the previously configured AK, otherwise calls will fail and may cause 403 errors
使用本Skill前,必须为之前配置的AK授予以下权限,否则调用会失败,可能返回403错误

1) RAM Permission Grant

1) RAM权限授予

  1. Visit Alibaba Cloud RAM Access Control
  2. Select the RAM user corresponding to the AK, click the "Add Permission" button, select AliyunBailianFullAccess and AliyunModelStudioReadOnlyAccess permission in the permission policy, and confirm to add the permission.
  1. 访问阿里云RAM访问控制页面
  2. 选择AK对应的RAM用户,点击"添加权限"按钮,在权限策略中选择 AliyunBailianFullAccessAliyunModelStudioReadOnlyAccess 权限,确认添加权限。

2) Bailian Workspace Permission Grant

2) 百炼工作区权限授予

  1. Visit Alibaba Cloud Bailian Permission Management
  2. If the RAM user corresponding to the AK does not exist, click "Add User" in the upper right corner of the page, select the corresponding RAM user and click confirm to add.
  3. Click "Permission Management" on the right side of the RAM user corresponding to the AK, click edit, and grant knowledge base related permissions.
  4. There is a 30s effective time after configuration, please wait patiently for a while.
  1. 访问阿里云百炼权限管理页面
  2. 如果AK对应的RAM用户不存在,点击页面右上角的 "添加用户",选择对应的RAM用户后点击确认添加。
  3. 点击AK对应的RAM用户右侧的 "权限管理",点击编辑,授予知识库相关权限。
  4. 配置完成后有30秒的生效时间,请耐心等待。

Available Scripts

可用脚本

All scripts are located in the
scripts/
directory:
ScriptPurposeParameters
check_env.js
Check environment configurationNone
list_workspace.js
Query workspace list
[maxResults]
list_indices.js
Query knowledge base list
workspaceId pageNumber pageSize
retrieve.js
Retrieve from specified knowledge base
workspaceId indexId query
所有脚本都位于
scripts/
目录下:
脚本用途参数
check_env.js
检查环境配置
list_workspace.js
查询工作区列表
[maxResults]
list_indices.js
查询知识库列表
workspaceId pageNumber pageSize
retrieve.js
从指定知识库检索内容
workspaceId indexId query

Workflow

工作流程

Step 1: Environment Check

步骤1:环境检查

Run
scripts/check_env.js
to check:
  • Whether npm packages are installed
  • Whether environment variables are configured
If not ready, prompt the user:
  • Packages not installed → Run
    npm install
    to install all dependencies in package.json
  • Missing environment variables → Guide user to configure
运行
scripts/check_env.js
检查以下项:
  • npm包是否已安装
  • 环境变量是否已配置
如果未准备就绪,提示用户:
  • 未安装依赖包 → 运行
    npm install
    安装package.json中的所有依赖
  • 缺少环境变量 → 引导用户进行配置

Step 2: Get Workspace ID

步骤2:获取工作区ID

Do not directly ask the user for workspaceId, instead automatically get the workspace list through the script.
Run
scripts/list_workspace.js
to get all available workspaces:
bash
node scripts/list_workspace.js
Return format:
json
{
  "workspaces": [
    {
      "workspaceId": "llm-bpp1p29i34jvoybx",
      "name": "Main Account Space"
    },
    {
      "workspaceId": "llm-hcghrtsbma82bwks",
      "name": "Podcast"
    }
  ]
}
Processing Logic:
  1. Get the workspace list
  2. If there is only one workspace, use it automatically and inform the user
  3. If there are multiple workspaces, display the list for user to select
  4. Record user selection to avoid repeated inquiries (until user wants to switch)
不要直接向用户索要workspaceId,而是通过脚本自动获取工作区列表。
运行
scripts/list_workspace.js
获取所有可用工作区:
bash
node scripts/list_workspace.js
返回格式:
json
{
  "workspaces": [
    {
      "workspaceId": "llm-bpp1p29i34jvoybx",
      "name": "主账号空间"
    },
    {
      "workspaceId": "llm-hcghrtsbma82bwks",
      "name": "播客"
    }
  ]
}
处理逻辑:
  1. 获取工作区列表
  2. 如果只有一个工作区,自动使用并告知用户
  3. 如果有多个工作区,展示列表供用户选择
  4. 记录用户选择,避免重复询问(直到用户想要切换)

Step 3: Query Knowledge Base List

步骤3:查询知识库列表

For each workspace, run
scripts/list_indices.js workspaceId pageNumber pageSize
to get the knowledge base list.
Batch Retrieval Strategy:
  1. Get all workspace lists from Step 2
  2. Iterate through each workspace, call
    list_indices.js
    to retrieve its knowledge bases
  3. Merge all knowledge base results, annotate the workspace they belong to
  4. pageNumber starts from 1, pageSize defaults to 100, if current page is not fully retrieved then continue to retrieve next page
Examples:
bash
undefined
针对每个工作区,运行
scripts/list_indices.js workspaceId pageNumber pageSize
获取知识库列表。
批量检索策略:
  1. 从步骤2获取所有工作区列表
  2. 遍历每个工作区,调用
    list_indices.js
    检索其下的知识库
  3. 合并所有知识库结果,标注其所属的工作区
  4. pageNumber从1开始,pageSize默认100,如果当前页未检索完则继续检索下一页
示例:
bash
undefined

Get knowledge bases from the first workspace

获取第一个工作区下的知识库

node scripts/list_indices.js llm-bpp1p29i34jvoybx 1 100
node scripts/list_indices.js llm-bpp1p29i34jvoybx 1 100

Get knowledge bases from the second workspace

获取第二个工作区下的知识库

node scripts/list_indices.js llm-hcghrtsbma82bwks 1 100

Return format:
```json
[
  {
    "indexId": "qf91w6402d",
    "name": "Product Documentation",
    "description": "Contains product user manuals, API documentation, etc."
  },
  {
    "indexId": "ip93d2pyvz",
    "name": "Customer Service Q&A",
    "description": "FAQ, customer service scripts"
  }
]
node scripts/list_indices.js llm-hcghrtsbma82bwks 1 100

返回格式:
```json
[
  {
    "indexId": "qf91w6402d",
    "name": "产品文档",
    "description": "包含产品用户手册、API文档等"
  },
  {
    "indexId": "ip93d2pyvz",
    "name": "客服问答",
    "description": "常见问题、客服话术"
  }
]

Step 4: Intelligent Knowledge Base Selection

步骤4:智能知识库选择

Based on the user's question and knowledge base descriptions, select 1-3 most relevant knowledge bases for retrieval.
Selection Strategy:
  • Match keywords (keywords in question vs knowledge base name/description)
  • Prioritize knowledge bases that explicitly contain relevant fields in their descriptions
  • If uncertain, select all or let user manually select
基于用户的问题和知识库描述,选择 1-3个最相关的知识库 进行检索。
选择策略:
  • 关键词匹配(问题中的关键词 vs 知识库名称/描述)
  • 优先选择描述中明确包含相关领域的知识库
  • 如果不确定,选择所有知识库或让用户手动选择

Step 5: Execute Retrieval

步骤5:执行检索

For each selected knowledge base, run
scripts/retrieve.js workspaceId indexId query
.
Return format, content inside each chunk represents chunk content, doc_name represents source document, score represents match score, title represents chunk section title:
json
{
  "indexId": "6fd13emwyj",
  "chunks": [
    {
      "content": "C. A small ball collides with a wall at 10 m/s, and bounces back with the same speed of 10 m/s. The magnitude of the ball's velocity change is 20 m/s. D. When an object's acceleration is positive, its velocity must increase. Example 1√ Problem Situation: As shown in the figure, Figure 2. Question 1. In the previous class, we drew the velocity-time relationship graph using a dot timer. Can you find the acceleration from it? 3. The ______________ from the v-t graph determines the magnitude of acceleration. Slope. 2. The slope value of the v-t graph represents: Acceleration value. 1. Calculate the magnitude of acceleration from the v-t graph. 4. If the v-t graph line is a sloping straight line, then the object's velocity changes uniformly, its acceleration is constant, and it moves with uniformly accelerated motion. Example 2. The three lines a, b, c in Figure 1.4-6 describe the motion of three objects A, B, C. First make a preliminary judgment about which object has the greatest acceleration, then calculate their accelerations based on the data in the graph, and explain the direction of acceleration. Analysis: Slope represents acceleration, acceleration tilts to the upper right, acceleration is positive, tilts to the lower right, acceleration is negative; so a and b are accelerating, c is decelerating, the object with the greatest acceleration, i.e., the steepest slope, is a. Description of velocity change - Acceleration. 1. Physical meaning: Describes how fast an object's velocity changes. 2. Definition: The ratio of the change in velocity to the time taken for that change. 3. Definition formula: 4. Vector nature: 5. Acceleration and velocity. Acceleration and velocity change. 6. Viewing acceleration from v-t graph: The slope value of the graph represents the acceleration value. Direction of a, accelerating motion. Direction of a, decelerating motion. Same as v0 direction.",
      "score": 0.6040189862251282,
      "doc_name": "Description of velocity change acceleration pptx-18 pages",
      "title": ""
    },
    {
      "content": "Section 4: Description of velocity change rate - Acceleration. High school physics, compulsory course 1, chapter 1. Learning objectives: Task 1: Understand the physical meaning of acceleration, be able to state the definition formula and unit of acceleration. Task 2: Be able to describe the relationship between the direction of acceleration and the direction of velocity. Task 3: Be able to distinguish between velocity, velocity change, and velocity change rate (acceleration). Understand variable speed motion. Task 4: Be able to determine acceleration from v-t graphs. 1. What is the reason for the distance between each car's final speed of 100 km/h? 2. What is the difference in their acceleration process motion? 3. Can you accurately compare the performance of these cars? Different rates of velocity change || Initial velocity (km/h) | Final velocity (km/h) | Time taken (s) | | A car start | 0 | 100 | 8.02 | | B car start | 0 | 100 | 9.53 | | C car start | 0 | 100 | 5.43 | | D car start | 0 | 100 | 4.47 | Table 1: Racing car 0~100 km/h sprint record. 4. With precise data, how to accurately compare the acceleration rate of cars? 5. Which car has the fastest velocity change? 6. Can you use other ways to compare the rate of velocity change? Observe the self-study draft Table 1, which object's velocity changes faster, A or B? | Time/s | 0 | 5 | 10 | 15 | | A v/(m·s-1) | 20 | 25 | 30 | 35 | | B v/(m·s-1) | 10 | 30 | 50 | 70 | | C v/(m·s-1) | 35 | 30 | 25 | 20 | | D v/(m·s-1) | 50 | 35 | 20 | 5 | Self-study draft Table 1: | Change | | 10 | | 40 |",
      "score": 0.6966111660003662,
      "doc_name": "Description of velocity change acceleration pptx-18 pages",
      "title": ""
    }
  ]
}
针对每个选中的知识库,运行
scripts/retrieve.js workspaceId indexId query
返回格式中,每个chunk里的content代表分片内容,doc_name代表源文档,score代表匹配得分,title代表分片章节标题:
json
{
  "indexId": "6fd13emwyj",
  "chunks": [
    {
      "content": "C. 一个小球以10 m/s的速度撞墙,以相同的10 m/s速度反弹。小球速度变化的大小为20 m/s。D. 当物体的加速度为正时,速度一定增加。示例1√ 问题场景:如图所示,图2。问题1. 上节课我们用打点计时器绘制了速度-时间关系图。你能从中求出加速度吗?3. v-t图的______________决定了加速度的大小。斜率。2. v-t图的斜率值代表:加速度值。1. 从v-t图计算加速度大小。4. 如果v-t图线是倾斜直线,则物体速度均匀变化,加速度恒定,做匀加速运动。示例2. 图1.4-6中的三条线a、b、c描述了三个物体A、B、C的运动。先初步判断哪个物体的加速度最大,然后根据图中的数据计算它们的加速度,并说明加速度的方向。分析:斜率代表加速度,加速度向右上方倾斜时为正,向右下方倾斜时为负;所以a和b在加速,c在减速,加速度最大的物体也就是斜率最陡的是a。速度变化的描述——加速度。1. 物理意义:描述物体速度变化的快慢。2. 定义:速度变化量与发生该变化所用时间的比值。3. 定义公式:4. 矢量性质:5. 加速度与速度。加速度与速度变化量。6. 从v-t图看加速度:图线的斜率值代表加速度值。a的方向,加速运动。a的方向,减速运动。与v0方向相同。",
      "score": 0.6040189862251282,
      "doc_name": "速度变化加速度描述pptx-18页",
      "title": ""
    },
    {
      "content": "第4节:速度变化率的描述——加速度。高中物理,必修1,第1章。学习目标:任务1:理解加速度的物理意义,能说出加速度的定义公式和单位。任务2:能描述加速度方向与速度方向的关系。任务3:能区分速度、速度变化量和速度变化率(加速度)。理解变速运动。任务4:能从v-t图确定加速度。1. 每辆车最终速度达到100 km/h的时间不同的原因是什么?2. 它们的加速过程运动有什么区别?3. 你能准确比较这些车的性能吗?速度变化率不同 || 初始速度(km/h) | 最终速度(km/h) | 耗时(s) | | A车启动 | 0 | 100 | 8.02 | | B车启动 | 0 | 100 | 9.53 | | C车启动 | 0 | 100 | 5.43 | | D车启动 | 0 | 100 | 4.47 | 表1:赛车0~100 km/h冲刺记录。4. 有了精确数据,如何准确比较汽车的加速度?5. 哪辆车的速度变化最快?6. 你能用其他方式比较速度变化率吗?观察自学草稿表1,A和B哪个物体的速度变化更快? | 时间/s | 0 | 5 | 10 | 15 | | A v/(m·s-1) | 20 | 25 | 30 | 35 | | B v/(m·s-1) | 10 | 30 | 50 | 70 | | C v/(m·s-1) | 35 | 30 | 25 | 20 | | D v/(m·s-1) | 50 | 35 | 20 | 5 | 自学草稿表1:| 变化量 | | 10 | | 40 |",
      "score": 0.6966111660003662,
      "doc_name": "速度变化加速度描述pptx-18页",
      "title": ""
    }
  ]
}

Step 6: Integrate Answer

步骤6:整合回答

Based on retrieval results:
  1. Sort by relevance (score descending)
  2. Extract key information
  3. Organize answer in natural language
  4. Please annotate the information source at the end of the generated answer (knowledge base name; document name; section name), can reference multiple documents and sections.
基于检索结果:
  1. 按相关性排序(得分降序)
  2. 提取关键信息
  3. 用自然语言组织回答
  4. 请在生成的回答末尾标注信息来源(知识库名称;文档名称;章节名称),可引用多个文档和章节。

Common Permission Errors:

常见权限错误:

{
  "code": "Index.NoWorkspacePermissions",
  "message": "No workspace permissions can be used, workspace: ssss",
  "requestId": "05072729-7958-5FE7-8F97-B54032231CCD",
  "status": "403"
}
If you see the above message, there may be 2 reasons: 1. The workspace does not exist. 2. The user has not completed the 2-step authorization above, please guide to check permissions and workspace existence.
{
  "code": "Index.NoWorkspacePermissions",
  "message": "无可用的工作区权限,工作区:ssss",
  "requestId": "05072729-7958-5FE7-8F97-B54032231CCD",
  "status": "403"
}
如果看到上述信息,可能有2个原因:1. 工作区不存在。2. 用户未完成上述2步授权,请引导检查权限和工作区是否存在。

Usage Example

使用示例

User: "What authentication methods does our product support?"
Flow:
  1. Check environment → Ready
  2. Get workspaceId →
    ws-123456
  3. Query knowledge base → Returns 3 knowledge bases
  4. Select knowledge base → "Product Documentation" (most relevant)
  5. Retrieve → Get authentication-related document chunks
  6. Answer → "According to product documentation, OAuth2.0, SAML, and API Key authentication methods are supported..."
用户: "我们的产品支持哪些认证方式?"
流程:
  1. 检查环境 → 已就绪
  2. 获取workspaceId →
    ws-123456
  3. 查询知识库 → 返回3个知识库
  4. 选择知识库 → "产品文档"(最相关)
  5. 检索 → 获取认证相关的文档分片
  6. 回答 → "根据产品文档,支持OAuth2.0、SAML和API Key三种认证方式..."

Notes

注意事项

  • Confirm workspaceId is correct before each retrieval
  • When retrieving from multiple knowledge bases, merge results and deduplicate
  • Sort retrieval results by score, prioritize high-relevance content
  • Credential configuration relies on Alibaba Cloud default credential chain, do not explicitly handle AK/SK
  • 每次检索前确认workspaceId正确
  • 从多个知识库检索时,合并结果并去重
  • 检索结果按得分排序,优先使用高相关性内容
  • 凭证配置依赖阿里云默认凭证链,不要显式处理AK/SK