AI 助理

建立新 AI 助理

POST /api/chatbots/

請求內容

請求參數

欄位	類型	必填	說明
name	string	是	機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
rag	string (uuid)	否	RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質
largeLanguageModel	string (uuid)	是	機器人使用的大型語言模型，用於生成回答
embeddingModel	string (uuid)	否	用於向量化文本的嵌入模型，非必填項目
rerankerModel	string (uuid)	否	用於重新排序的模型，非必填項目
instructions	string	否	機器人的角色指令，用於描述機器人的角色和行為
knowledgeBases	array[IdName]	否	機器人可存取的知識庫列表
organization	string (uuid)	否	機器人所屬的組織，如果為空則為個人機器人
builtInWorkflow	string (uuid)	否	內建工作流程，用於預定義的處理流程
replyMode	object	否	回覆模式：一般回覆或串流回覆 normal: 正常 ; template: 模板 ; hybrid: 混合 ; workflow: 工作流 ; agent: 代理;
template	string	否	模板模式、混合模式所使用的模板
unanswerableTemplate	string	否	模板模式、混合模式無法回答時的模板
totalWordsCount	integer (int64)	否	累積的使用總字數
outputMode	object	否	輸出模式：文字、表格或自定義格式 text: 文字 ; json_schema: JSON Schema;
rawOutputFormat	object	否	自定義輸出格式的JSON結構定義
databaseUrl	string	否	資料庫連線URL（用於資料庫查詢功能）
databaseType	string	否	資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle
includeTables	object	否	包含的資料表列表（用於資料庫查詢功能）
groups	array[IdName]	否	機器人可存取的群組列表
toolkits	array[ToolSummary]	否	機器人使用的工具套件列表
tools	array[ToolSummary]	否	機器人可使用的工具列表
agentMode	object	否	代理模式：一般、SQL或工作流程模式 normal: 正常 ; canvas: 畫布;
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
enableEvaluation	boolean	否
enableInlineCitations	boolean	否	啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記
enableKnowledgeBaseRag	boolean	否	啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool
enableAgenticTextToSql	boolean	否	啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具
customMaxLlmOutputTokens	integer	否	自訂最大 LLM 輸出 token 數，最小值為 512

請求結構範例

{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

請求範例值

{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "範例字串",
  "databaseType": "範例字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableKnowledgeBaseRag": true,
  "enableAgenticTextToSql": true,
  "customMaxLlmOutputTokens": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "databaseUrl": "範例字串",
    "databaseType": "範例字串",
    "includeTables": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "toolkits": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableKnowledgeBaseRag": true,
    "enableAgenticTextToSql": true,
    "customMaxLlmOutputTokens": 123
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases": [ // 機器人配置的資料庫列表（用於 Text-to-SQL 功能）
    {
      "id": string (uuid)
      "name": string // 顯示用的名稱，例如：主要業務DB、分析DB
      "databaseType":  // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle、MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
      {
      }
      "databaseUrl": string // 資料庫連線字串
      "includeTables"?: object // 指定要查詢的資料表列表，格式: {"tables": ["table1", "table2"]}。MaiAgent 類型會自動從上傳的檔案中取得，不需要手動設定 (非必填)
      "isActive"?: boolean // 停用後將不會在 Text-to-SQL 查詢中使用此資料庫 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "databaseType": {},
      "databaseUrl": "回應字串",
      "includeTables": null,
      "isActive": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "回應字串",
  "databaseType": "回應字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableKnowledgeBaseRag": false,
  "enableAgenticTextToSql": false,
  "customMaxLlmOutputTokens": 456
}

---

列出 Embedding Model

GET /api/embedding-models/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/embedding-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]

---

列出 Reranker Model

GET /api/reranker-models/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/reranker-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]

---

取得 AI 助理列表

GET /api/chatbots/

參數

參數名稱	必填	類型	說明
largeLanguageModel	❌	string
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
pagination	❌	string	是否分頁 (true/false)
query	❌	string
replyMode	❌	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rag": { // RAG 的基礎序列化器
      {
        "id": string (uuid)
        "name": string
      }
      }
      "largeLanguageModel": { // LLM 的基礎序列化器，只包含基本字段
      {
        "id": string (uuid)
        "name": string
      }
      }
      "embeddingModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "rerankerModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "knowledgeBases": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "tools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "toolkits": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "agentMode"?:  // 代理模式，有畫布模式和一般模式，畫布模式是使用畫布來生成回答，一般模式是使用一般模式來生成回答

* `normal` - 正常
* `canvas` - 畫布 (非必填)
      {
      }
      "replyMode"?:  // 回傳模式，有一般模式、模板模式、混合模式、工作流模式、Agent模式

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
      {
      }
      "updatedAt": string (timestamp)
      "enableEvaluation"?: boolean // 非必填
      "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
      "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
      "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
      "numberOfRetrievedChunks"?: integer // 非必填
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rag": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "embeddingModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "rerankerModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "toolkits": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "agentMode": {},
      "replyMode": {},
      "updatedAt": "回應字串",
      "enableEvaluation": false,
      "enableInlineCitations": false,
      "enableKnowledgeBaseRag": false,
      "enableAgenticTextToSql": false,
      "numberOfRetrievedChunks": 456
    }
  ]
}

---

取得特定 AI 助理

GET /api/chatbots/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases": [ // 機器人配置的資料庫列表（用於 Text-to-SQL 功能）
    {
      "id": string (uuid)
      "name": string // 顯示用的名稱，例如：主要業務DB、分析DB
      "databaseType":  // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle、MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
      {
      }
      "databaseUrl": string // 資料庫連線字串
      "includeTables"?: object // 指定要查詢的資料表列表，格式: {"tables": ["table1", "table2"]}。MaiAgent 類型會自動從上傳的檔案中取得，不需要手動設定 (非必填)
      "isActive"?: boolean // 停用後將不會在 Text-to-SQL 查詢中使用此資料庫 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "databaseType": {},
      "databaseUrl": "回應字串",
      "includeTables": null,
      "isActive": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "回應字串",
  "databaseType": "回應字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableKnowledgeBaseRag": false,
  "enableAgenticTextToSql": false,
  "customMaxLlmOutputTokens": 456
}

---

更新 AI 助理

PUT /api/chatbots/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot.

請求內容

請求參數

欄位	類型	必填	說明
name	string	是	機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
rag	string (uuid)	否	RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質
largeLanguageModel	string (uuid)	是	機器人使用的大型語言模型，用於生成回答
embeddingModel	string (uuid)	否	用於向量化文本的嵌入模型，非必填項目
rerankerModel	string (uuid)	否	用於重新排序的模型，非必填項目
instructions	string	否	機器人的角色指令，用於描述機器人的角色和行為
knowledgeBases	array[IdName]	否	機器人可存取的知識庫列表
organization	string (uuid)	否	機器人所屬的組織，如果為空則為個人機器人
builtInWorkflow	string (uuid)	否	內建工作流程，用於預定義的處理流程
replyMode	object	否	回覆模式：一般回覆或串流回覆 normal: 正常 ; template: 模板 ; hybrid: 混合 ; workflow: 工作流 ; agent: 代理;
template	string	否	模板模式、混合模式所使用的模板
unanswerableTemplate	string	否	模板模式、混合模式無法回答時的模板
totalWordsCount	integer (int64)	否	累積的使用總字數
outputMode	object	否	輸出模式：文字、表格或自定義格式 text: 文字 ; json_schema: JSON Schema;
rawOutputFormat	object	否	自定義輸出格式的JSON結構定義
databaseUrl	string	否	資料庫連線URL（用於資料庫查詢功能）
databaseType	string	否	資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle
includeTables	object	否	包含的資料表列表（用於資料庫查詢功能）
groups	array[IdName]	否	機器人可存取的群組列表
toolkits	array[ToolSummary]	否	機器人使用的工具套件列表
tools	array[ToolSummary]	否	機器人可使用的工具列表
agentMode	object	否	代理模式：一般、SQL或工作流程模式 normal: 正常 ; canvas: 畫布;
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
enableEvaluation	boolean	否
enableInlineCitations	boolean	否	啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記
enableKnowledgeBaseRag	boolean	否	啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool
enableAgenticTextToSql	boolean	否	啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具
customMaxLlmOutputTokens	integer	否	自訂最大 LLM 輸出 token 數，最小值為 512

請求結構範例

{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

請求範例值

{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "範例字串",
  "databaseType": "範例字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableKnowledgeBaseRag": true,
  "enableAgenticTextToSql": true,
  "customMaxLlmOutputTokens": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "databaseUrl": "範例字串",
    "databaseType": "範例字串",
    "includeTables": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "toolkits": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableKnowledgeBaseRag": true,
    "enableAgenticTextToSql": true,
    "customMaxLlmOutputTokens": 123
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases": [ // 機器人配置的資料庫列表（用於 Text-to-SQL 功能）
    {
      "id": string (uuid)
      "name": string // 顯示用的名稱，例如：主要業務DB、分析DB
      "databaseType":  // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle、MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
      {
      }
      "databaseUrl": string // 資料庫連線字串
      "includeTables"?: object // 指定要查詢的資料表列表，格式: {"tables": ["table1", "table2"]}。MaiAgent 類型會自動從上傳的檔案中取得，不需要手動設定 (非必填)
      "isActive"?: boolean // 停用後將不會在 Text-to-SQL 查詢中使用此資料庫 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "databaseType": {},
      "databaseUrl": "回應字串",
      "includeTables": null,
      "isActive": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "回應字串",
  "databaseType": "回應字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableKnowledgeBaseRag": false,
  "enableAgenticTextToSql": false,
  "customMaxLlmOutputTokens": 456
}

---

部分更新 AI 助理

PATCH /api/chatbots/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否	機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
rag	string (uuid)	否	RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質
largeLanguageModel	string (uuid)	否	機器人使用的大型語言模型，用於生成回答
embeddingModel	string (uuid)	否	用於向量化文本的嵌入模型，非必填項目
rerankerModel	string (uuid)	否	用於重新排序的模型，非必填項目
instructions	string	否	機器人的角色指令，用於描述機器人的角色和行為
knowledgeBases	array[IdName]	否	機器人可存取的知識庫列表
organization	string (uuid)	否	機器人所屬的組織，如果為空則為個人機器人
builtInWorkflow	string (uuid)	否	內建工作流程，用於預定義的處理流程
replyMode	object	否	回覆模式：一般回覆或串流回覆 normal: 正常 ; template: 模板 ; hybrid: 混合 ; workflow: 工作流 ; agent: 代理;
template	string	否	模板模式、混合模式所使用的模板
unanswerableTemplate	string	否	模板模式、混合模式無法回答時的模板
totalWordsCount	integer (int64)	否	累積的使用總字數
outputMode	object	否	輸出模式：文字、表格或自定義格式 text: 文字 ; json_schema: JSON Schema;
rawOutputFormat	object	否	自定義輸出格式的JSON結構定義
databaseUrl	string	否	資料庫連線URL（用於資料庫查詢功能）
databaseType	string	否	資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle
includeTables	object	否	包含的資料表列表（用於資料庫查詢功能）
groups	array[IdName]	否	機器人可存取的群組列表
toolkits	array[ToolSummary]	否	機器人使用的工具套件列表
tools	array[ToolSummary]	否	機器人可使用的工具列表
agentMode	object	否	代理模式：一般、SQL或工作流程模式 normal: 正常 ; canvas: 畫布;
numberOfRetrievedChunks	integer	否	提取的參考資料數量，預設為 12，最小值為 1
enableEvaluation	boolean	否
enableInlineCitations	boolean	否	啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記
enableKnowledgeBaseRag	boolean	否	啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool
enableAgenticTextToSql	boolean	否	啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具
customMaxLlmOutputTokens	integer	否	自訂最大 LLM 輸出 token 數，最小值為 512

請求結構範例

{
  "name"?: string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人 (非必填)
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel"?: string (uuid) // 機器人使用的大型語言模型，用於生成回答 (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

請求範例值

{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "範例字串",
  "databaseType": "範例字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableKnowledgeBaseRag": true,
  "enableAgenticTextToSql": true,
  "customMaxLlmOutputTokens": 123
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "databaseUrl": "範例字串",
    "databaseType": "範例字串",
    "includeTables": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "toolkits": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableKnowledgeBaseRag": true,
    "enableAgenticTextToSql": true,
    "customMaxLlmOutputTokens": 123
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases": [ // 機器人配置的資料庫列表（用於 Text-to-SQL 功能）
    {
      "id": string (uuid)
      "name": string // 顯示用的名稱，例如：主要業務DB、分析DB
      "databaseType":  // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle、MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
      {
      }
      "databaseUrl": string // 資料庫連線字串
      "includeTables"?: object // 指定要查詢的資料表列表，格式: {"tables": ["table1", "table2"]}。MaiAgent 類型會自動從上傳的檔案中取得，不需要手動設定 (非必填)
      "isActive"?: boolean // 停用後將不會在 Text-to-SQL 查詢中使用此資料庫 (非必填)
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "databaseUrl"?: string // 資料庫連線URL（用於資料庫查詢功能） (非必填)
  "databaseType"?: string // 資料庫類型選項，有 MySQL、PostgreSQL、MSSQL、Oracle (非必填)
  "includeTables"?: object // 包含的資料表列表（用於資料庫查詢功能） (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "toolkits"?: [ // 機器人使用的工具套件列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableKnowledgeBaseRag"?: boolean // 啟用後使用 query_files/retrieve_text_nodes/get_surrounding_context 工具，否則使用 internal_search_tool (非必填)
  "enableAgenticTextToSql"?: boolean // 啟用後，使用 Agentic Text to SQL 工具，否則使用原本的 Text to SQL 工具 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "databaseType": {},
      "databaseUrl": "回應字串",
      "includeTables": null,
      "isActive": false,
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "databaseUrl": "回應字串",
  "databaseType": "回應字串",
  "includeTables": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "toolkits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableKnowledgeBaseRag": false,
  "enableAgenticTextToSql": false,
  "customMaxLlmOutputTokens": 456
}

---

刪除 AI 助理

DELETE /api/chatbots/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---