# 角色指令

最後更新：2025-11-14

## 概述

角色指令（System Prompt）是定義 AI 助理行為和回答風格的核心設定。透過精心設計的角色指令，您可以讓 AI 助理扮演特定角色、遵循特定規則，並以符合您業務需求的方式回答問題。

放置對於 AI 助理的角色描述與指令，包含回答時應該遵守的規則與 SOP 等。可想像為每次回覆時都需要遵守的規則。只需要放置精華的部分，太大量的角色指令可能導致 AI 無法吸收過多的規則，導致不遵守規則。大量或是當有問到相關問題才需要調取的資料則放置於知識庫。

## Metadata 處理機制

### 什麼是 Metadata

Metadata（元資料）是描述知識庫文件的附加資訊，例如：

* 文件分類
* 建立日期
* 作者資訊
* 權限標籤
* 其他自訂屬性

在 RAG（檢索增強生成）系統中，Metadata 扮演重要角色，幫助 AI 助理更精確地篩選和使用知識庫內容。

### Metadata 排除邏輯優化

MaiAgent 平台已優化 Metadata 處理邏輯，確保系統更準確地處理元資料：

#### 優化內容

**移除重複的排除邏輯**

在先前版本中，系統可能會重複檢查和排除某些 Metadata key，造成不必要的效能開銷。新版本已移除這些重複邏輯，確保：

* **處理效率提升**：減少重複的檢查步驟
* **邏輯更清晰**：避免相同的排除規則重複執行
* **維護性更好**：程式碼結構更簡潔

**影響範圍**

這個優化主要影響系統內部的 Metadata 處理流程，對使用者來說：

* ✅ Metadata 篩選功能正常運作
* ✅ 檢索效能得到改善
* ✅ 回答準確性保持一致
* ✅ 無需調整現有設定

### Metadata 在角色指令中的應用

#### 基本使用方式

在角色指令中，您可以指示 AI 助理如何使用 Metadata：

```
你是一個專業的客服助理。在回答問題時：
1. 優先使用標記為「official」類別的文件
2. 如果找不到官方文件，再參考「community」類別
3. 始終在回答中註明資訊來源的類別
```

#### 進階 Metadata 應用

**權限管理**

```
根據使用者的權限等級，只使用相應的文件：
- VIP 客戶：可參考所有文件
- 一般客戶：只參考標記為「public」的文件
- 新客戶：只參考「basic」類別的文件
```

**時效性控制**

```
回答問題時，請遵循以下規則：
1. 優先使用最近 3 個月內更新的文件
2. 如果使用較舊的文件，請在回答中說明可能需要確認最新資訊
3. 忽略標記為「archived」的文件
```

**多語言支援**

```
根據使用者的語言偏好選擇文件：
- 繁體中文使用者：使用 lang="zh-TW" 的文件
- 英文使用者：使用 lang="en" 的文件
- 如果沒有對應語言，使用預設語言並說明
```

## Metadata 最佳實踐

### 1. 定義清晰的 Metadata 結構

建立標準化的 Metadata 架構：

```json
{
  "category": "product-info",
  "language": "zh-TW",
  "access_level": "public",
  "last_updated": "2025-11-14",
  "status": "active"
}
```

### 2. 在角色指令中明確說明 Metadata 使用規則

```
# 文件使用規則

## 優先順序
1. status = "active" 且 access_level 符合使用者權限
2. category 符合問題主題
3. last_updated 在最近 6 個月內

## 排除規則
- 忽略 status = "draft" 的文件
- 忽略 access_level 高於使用者權限的文件
```

### 3. 定期檢視 Metadata 設定

* 確認 Metadata 分類是否符合實際使用需求
* 檢查是否有未使用的 Metadata key
* 評估 Metadata 對檢索效能的影響

## 技術細節

### Metadata 處理流程

```
1. 使用者提問
   ↓
2. 系統解析問題並提取關鍵資訊
   ↓
3. 根據 Metadata 篩選候選文件
   ↓
4. 檢索系統找出最相關的文件片段
   ↓
5. LLM 基於角色指令和檢索結果生成回答
```

### 效能考量

* **索引建立**：Metadata 會在檔案上傳時建立索引
* **查詢效率**：簡單的 Metadata 篩選通常在毫秒級完成
* **複雜查詢**：多重條件的 Metadata 篩選可能需要較長時間

### 系統限制

* 每個文件建議不超過 20 個 Metadata key
* Metadata value 建議使用簡短的字串或數值
* 避免在 Metadata 中存放大量文字內容

## 角色指令範例

<mark style="color:orange;">你是一位專業的XXX AI助理。</mark>

\ <mark style="color:blue;">你應該 (加強回覆)：</mark>

1. <mark style="color:blue;">提供清晰、準確且有幫助的回答</mark>
2. <mark style="color:blue;">保持友善且專業的對話態度</mark>
3. <mark style="color:blue;">根據使用者語言回答，中文使用繁體中文</mark>
4. <mark style="color:blue;">避免提供有害或不當的建議</mark>
5. <mark style="color:blue;">尊重用戶隱私,不洩漏敏感資訊</mark>
6. <mark style="color:blue;">使用正確的繁體中文進行回覆</mark>
7. <mark style="color:blue;">根據上下文調整回答的詳細程度</mark>
8. <mark style="color:blue;">在適當時提供延伸建議或相關資訊</mark>
9. <mark style="color:blue;">回覆時，請先確認使用者資訊是否提供清楚，提供清楚再做回答</mark>
10. <mark style="color:blue;">適時使用舉例來說明複雜概念</mark>

<mark style="color:red;">你不應該 (限制回覆)：</mark>

1. <mark style="color:red;">散播錯誤資訊或未經證實的說法</mark>
2. <mark style="color:red;">做出偏見或歧視性的言論</mark>
3. <mark style="color:red;">討論違法或不當的內容</mark>
4. <mark style="color:red;">假裝自己是真人</mark>
5. <mark style="color:red;">超出AI助理的能力範圍</mark>
6. <mark style="color:red;">不在知識庫範圍的問題，請回覆「不好意思，目前無法回答這個問題」</mark>

## 角色指令模板

```yaml
# Persona
(描述 AI 助理的角色)

# Context
(描述任務背景)

# Task
## Input
(描述會提供什麼資料)

## Output
(描述輸出內容，包含格式或語氣，也可以提供 Template)

<template>
...
</template>

# Instructions
(任務的步驟)

1. ...
2. ...
3. ...
...

# Example
(輸出的範例，1~3個)

<example>
...
</example>

<example>
...
</example>

...

# Constraints
(輸出的限制)

1. ...
2. ...
3. ...
...
```

## 相關資源

* [角色指令設計指南](https://docs.maiagent.ai/build/system-prompt)
* [文件管理：標籤及元資料](https://docs.maiagent.ai/km/tags-and-metadata)
* [查詢元資料](https://docs.maiagent.ai/org/querymetadata)

{% hint style="info" %}
[生成角色指令的 AI 工具](https://chat.maiagent.ai/web-chats/4b67b140-db5f-40dc-bce3-f2217e9574bd)
{% endhint %}