# 角色指令

最後更新：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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/ai-agents/system-prompt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.