alibabacloud-bailian-rag-knowledgebase

What this skill does

# Bailian Knowledge Base Retrieval

This Skill provides query and retrieval capabilities for Alibaba Cloud Bailian Knowledge Base, supporting intelligent selection across multiple knowledge bases.

## 🚀 Initial Setup (Required for First-time Use)

### 1. Install Dependencies

```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

### 2. Configure Alibaba Cloud Credentials

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
# Configure credentials using Alibaba Cloud 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

### 3. Important Prerequisite: Activate Bailian and Knowledge Base Service

**Before using this skill, you must first activate the knowledge base service in the Alibaba Cloud Bailian console!**

1. Visit [Bailian Knowledge Base page](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/knowledge-base)
2. Click the **"Activate Now"** button
3. Confirm activation and wait for the service to take effect (usually 1-2 minutes)

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

**Before using this skill, you must grant the following permissions to the previously configured AK, otherwise calls will fail and may cause 403 errors**

#### 1) RAM Permission Grant
1. Visit [Alibaba Cloud RAM Access Control](https://ram.console.aliyun.com/users)
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.
#### 2) Bailian Workspace Permission Grant
1. Visit [Alibaba Cloud Bailian Permission Management](https://bailian.console.aliyun.com/cn-beijing?tab=app#/authority)
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.

## Available Scripts

All scripts are located in the `scripts/` directory:

| Script | Purpose | Parameters |
|--------|---------|------------|
| `check_env.js` | Check environment configuration | None |
| `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` |

## Workflow

### Step 1: Environment Check

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

### Step 2: Get Workspace 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)

### Step 3: Query Knowledge Base List

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
# Get knowledge bases from the first workspace
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"
  }
]
```

### Step 4: Intelligent Knowledge Base Selection

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

### Step 5: Execute Retrieval

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. Defini