PAI-RAG 服務 API 參考 (v0.4.x) - Platform For AI

本文檔適用於 v0.4.x 版本的 PAI-RAG 服務，提供完整的 API 介面定義、請求樣本與核心概念說明，旨在協助開發人員快速、高效地將 PAI-RAG 的能力整合到自己的應用中。

準備工作：擷取服務訪問地址和Token

通過API介面調用RAG服務前，需要擷取RAG服務的訪問地址和認證令牌。所有 API 請求都需要在 HTTP Authorization 中攜帶EAS_TOKEN。

在下文API介面說明中出現的$EAS_SERVICE_URL和$EAS_TOKEN是環境變數，使用前需要先設定。擷取方式如下：

登入PAI控制台，在頁面上方選擇目標地區，並在右側選擇目標工作空間，然後單擊進入EAS。
單擊目標服務名稱，然後在基本信息地區，單擊查看调用信息。
在调用信息頁面，擷取公網/VPC調用地址（EAS_SERVICE_URL）和Token（EAS_TOKEN）。
重要
- 請將EAS_SERVICE_URL末尾的斜杠（/）刪除。
- 使用公網調用地址：調用用戶端支援訪問公網。
- 使用VPC調用地址：調用用戶端必須與RAG服務位於同一個專用網路內。

擷取到EAS_SERVICE_URL和EAS_TOKEN後，建議將它們設定為環境變數，方便後續API調用：

export EAS_SERVICE_URL="您的服務地址"
export EAS_TOKEN="您的Token"

設定環境變數後，後續的curl命令可以直接使用$EAS_SERVICE_URL和$EAS_TOKEN引用這些值。

Chat API

Chat API 是一個支援智能代理（Agent）和檢索增強產生（RAG）的流式聊天介面。它擴充了 OpenAI 相容的聊天協議，支援知識庫檢索、多步驟推理、外部工具調用等進階功能，適用於構建智能對話系統、知識問答機器人等情境。

重要

推薦調用Chat的方式是配置一個屬於你的Chat應用，假設應用程式名稱為my_assistant，並選擇合適的知識庫、連網搜尋配置。

POST $EAS_SERVICE_URL/v1/chat/completions

功能描述: 發起一次對話請求。通過指定 model 參數來調用一個預先配置好的 Chat 應用，該應用可能關聯了知識庫、搜尋工具等。

請求體 (application/json)

欄位	類型	是否必填	描述
`model`	String	是	您建立的 Chat 應用程式名稱。
`messages`	Array	是	對話歷史列表，遵循 OpenAI 格式。
`stream`	Boolean	否	是否以流式模式返迴響應，預設為 `false`。

請求體樣本

{
    "model": "my_assistant",
    "messages": [
        {
            "role": "user",
            "content": "PAI-RAG 有哪些核心功能？"
        }
    ],
    "stream": true
}

響應體

與 OpenAI chat.completions 介面的響應格式相容。

OpenAI用戶端調用樣本:

from openai import OpenAI
import os
EAS_ENDPOINT = os.getenv("EAS_SERVICE_URL")
EAS_TOKEN = os.getenv("EAS_TOKEN")
client = OpenAI(
    base_url=EAS_ENDPOINT,
    api_key=EAS_TOKEN
)
response = client.chat.completions.create(
    model="my_assistant",  # 替換為真實的Chat應用程式名稱
    messages=[
        {"role": "user", "content": "你好"}
    ],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content)

知識庫管理員

建立知識庫

建立一個新的知識庫，並可以指定其資料分塊、嵌入和檢索等配置。

POST $EAS_SERVICE_URL/v1/config/knowledgebases

請求	curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "這是一個樣本知識庫", "chunk_config": { "parser_type": "structure", "separator": "\n\n", "chunk_size": 1000, "chunk_overlap": 50 }, "embedding_model": "BAAI/bge-m3", "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 5, "similarity_threshold": 0.2, "enable_rerank": true, "rerank_model": "qwen3-reranker", "vector_weight": 0.7 } }'
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
請求體（Request Body）
name `string`（必選）知識庫名稱。
description `string`（可選）知識庫的描述資訊。
embedding_model `string`（必選）嵌入模型的名稱或路徑。支援本地或遠程模型。
chunk_config `object`（可選）資料分塊配置。屬性 parser_type `string`（可選）解析器類型。可選值：`structure`、`table`、`token` 、`paragraph`。 separator `string`（可選）自訂分隔字元。 chunk_size `int`（可選）每個資料區塊的最大長度（單位：字元）。 chunk_overlap `int`（可選）相鄰資料區塊之間的重疊長度（單位：字元）。 image_caption_model `string`（可選）圖片理解模型。
retrieval_config `object`（可選）檢索策略配置。屬性 retrieval_mode `string`（可選）檢索模式。可選值：`hybrid`（混合檢索）、`vector`（向量檢索）。 top_k `int`（可選）檢索返回的最相關資料區塊數量。 similarity_threshold `float`（可選）相似性得分閾值，低於此值的結果將被過濾。 enable_rerank `bool`（可選）是否啟用重排模型以最佳化檢索結果。重要需先在PAI-RAG的WebUI中配置好Reranker模型，才可使用。 rerank_model `string`（可選）重排模型的名稱或路徑。 vector_weight `float`（可選）在混合檢索中，向量檢索的權重。

響應樣本

{
    "code": 200,
    "message": "知識庫建立成功。",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "這是一個樣本知識庫",
        "updated_at": "2026-02-27T02:35:01.121046Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

擷取知識庫列表

擷取當前服務下的知識庫列表，支援分頁。

GET $EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKE"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL查詢參數（Query parameters）
page `int`（可選）頁碼，預設值為 `1`。
size `int`（可選）每頁返回的數量，預設值為 `10`，上限為 `1000`。

響應樣本

{
    "code": 200,
    "message": "擷取知識庫列表成功",
    "data": {
        "items": [
            {
                "name": "example_kb",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-27T02:35:01.121035Z",
                "description": "這是一個樣本知識庫",
                "updated_at": "2026-02-27T02:35:01.121046Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "a4815ee728a64e9c83a3d891dbc1c956",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "hybrid",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": true,
                    "rerank_model": "qwen3-reranker",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 0
            },
            {
                "name": "iPhone16",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-25T08:57:07.085859Z",
                "description": "",
                "updated_at": "2026-02-25T09:01:40.035292Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "08f6bb77fd3441099fb5b19e4f10d67b",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "vector",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": false,
                    "rerank_model": "",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 2
            }
        ],
        "total": 2,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

擷取指定知識庫（通過kb_id）

擷取指定 ID 的知識庫的詳細資料。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。

響應樣本

{
    "code": 200,
    "message": "查詢知識庫成功。",
    "data": {
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "tenant_id": "__default_tenant_id__",
        "name": "example_kb",
        "description": "這是一個樣本知識庫",
        "created_at": "2026-02-27T02:35:01.121035+00:00",
        "updated_at": "2026-02-27T02:35:01.121046+00:00",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

修改知識庫

修改一個已存在的知識庫。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

請求	curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "樣本", "id": "kb4451867a6d0f4166babddb7a048a311d", "embedding_model": "BAAI/bge-m3", "chunk_config": { "chunk_size": 1000, "chunk_overlap": 50, "parser_type": "structure", "separator": "\n\n" }, "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 6, "similarity_threshold": 0.2, "vector_weight": 0.7, "enable_rerank": true, "rerank_model": "qwen3-reranker" } }'
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
請求體（Request Body）
請求體參數同建立知識庫介面，包括 name、description、embedding_model、chunk_config、retrieval_config 等欄位。

響應樣本

{
    "code": 200,
    "message": "知識庫更新成功。",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "樣本",
        "updated_at": "2026-02-27T07:26:55.543217Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 6,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

刪除指定知識庫

刪除一個指定的知識庫及其包含的所有檔案和索引。此操作無法復原，請謹慎使用。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

請求	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。

響應樣本

{"code":200,"message":"知識庫刪除成功。","data":null}

檔案管理

上傳檔案

向指定知識庫上傳一個或多個檔案。這是一個非同步介面，會立即返迴文件資訊，並在後台進行解析和索引。支援的檔案格式包括 PDF、DOCX、TXT 等。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

請求	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: multipart/form-data' \ --form 'files=@"/path/to/your/file.pdf"'`
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`multipart/form-data`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
請求體參數（Request Body）
files `file`（必選）要上傳的檔案（支援 PDF/DOCX/TXT 等）。可以一次上傳多個。

響應樣本

{
    "code": 200,
    "message": "File upload successful",
    "data": [
        {
            "file_content_length": 0,
            "status": "pending",
            "file_source": null,
            "failed_reason": null,
            "file_name": "EAS模型服務概述.pdf",
            "active": true,
            "tenant_id": "__default_tenant_id__",
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
            "created_at": "2026-02-27T07:30:10.875488Z",
            "id": "2540b5414f2d422291cea3162eb8e1e0",
            "file_extension": ".pdf",
            "updated_at": "2026-02-27T07:30:10.875503Z",
            "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
            "file_size": 889027,
            "file_metadata": {
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
                "file_name": "EAS模型服務概述.pdf",
                "file_size": 889027,
                "file_extension": ".pdf"
            },
            "message_id": "tmp-1772177410",
            "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
            "chunk_config": {
                "chunk_size": 1000,
                "chunk_overlap": 50,
                "parser_type": "structure",
                "separator": "\n\n",
                "image_caption_model": null,
                "image_caption_provider_name": "openai_like",
                "table_config": {
                    "concat_rows": false,
                    "row_joiner": "\n",
                    "header_index_max": 0,
                    "format_sheet_data_to_json": false,
                    "sheet_column_filters": null,
                    "question_column_index": 0,
                    "answer_column_index": 1
                }
            },
            "file_content": "",
            "file_version": 1772177410
        }
    ]
}

列出檔案

列出指定知識庫中的檔案，支援按檔案名稱和狀態進行篩選和分頁。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files?query=EAS&status=succeeded&page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
URL查詢參數（Query parameters）
query `string`（可選）根據檔案名稱進行模糊比對。
status `string`（可選）根據檔案處理狀態篩選。不傳為全部，可選值：`pending`（等待）、`succeeded`（成功）、`failed`（失敗）、`persisting`（索引中）、`parsing`（解析中）。
page `int`（可選）頁碼，預設值為 1。
size `int`（可選）每頁返回的數量，預設值為 10。

響應樣本

{
    "code": 200,
    "message": "查詢檔案清單成功",
    "data": {
        "items": [
            {
                "file_content_length": 0,
                "status": "succeeded",
                "file_source": null,
                "failed_reason": null,
                "file_name": "EAS模型服務概述.pdf",
                "active": true,
                "tenant_id": "__default_tenant_id__",
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
                "created_at": "2026-02-27T07:30:10.875488Z",
                "id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_extension": ".pdf",
                "updated_at": "2026-02-27T07:30:10.875503Z",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "file_size": 889027,
                "file_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
                    "file_name": "EAS模型服務概述.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf"
                },
                "message_id": "tmp-1772177410",
                "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
                "chunk_config": null,
                "file_content": "",
                "file_version": 1772177410
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

擷取單個檔案資訊

擷取單個檔案的詳細資料，常用於輪詢檔案處理狀態。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。

響應樣本

{
    "code": 200,
    "message": "File query successful",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS模型服務概述.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:30:10.875503Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
            "file_name": "EAS模型服務概述.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "file_url": "http://rag-test-****.oss-cn-hangzhou.aliyuncs.com/pairag_knowledgebases%2Fa4815ee728a64e9c83a3d891dbc1c956%2Fdocs%2FEAS%E6%A8%A1%E5%9E%8B%E6%9C%8D%E5%8A%A1%E6%A6%82%E8%BF%B0.pdf?OSSAccessKeyId=******&Expires=1772181413&Signature=IME****MxJ7Ys2%2BMwckrZsNfg%3D"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772177410
    }
}

重新處理檔案

觸發對一個檔案（例如處理失敗或內容已更新的檔案）的重新處理。這是一個非同步作業，會建立一個新的處理任務，並將檔案狀態重設為 pending。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

請求	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \`
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。

響應樣本

{
    "code": 200,
    "message": "Successfully added 1 files to the reprocessing queue.",
    "data": 1
}

刪除檔案

從知識庫中刪除一個指定的檔案及其關聯的資料區塊和索引。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

請求	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。

響應樣本

{
    "code": 200,
    "message": "刪除知識庫檔案成功。",
    "data": null
}

資料分塊管理

查看檔案分塊

查看指定檔案被切分後的資料區塊列表，支援分頁。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。
URL查詢參數（Query parameters）
page `int`（可選）頁碼，預設值為 1。
size `int`（可選）每頁返回的數量，預設值為 10。

響應樣本

{
    "code": 200,
    "message": "Chunk list retrieval successful",
    "data": {
        "items": [
            {
                "active": true,
                "text": "EAS 模型服務概述******等能力。\n\n",
                "chunk_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
                    "file_name": "EAS模型服務概述.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf",
                    "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
                    "token_count": 196,
                    "doc_id": "2540b5414f2d422291cea3162eb8e1e0",
                    "images_info": []
                },
                "file_id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_version": 0,
                "index": 0,
                "updated_at": "2026-02-27T07:42:00.167502Z",
                "status": "succeeded",
                "tenant_id": "__default_tenant_id__",
                "id": "e2b0d936158f4656a6cacb5ab639de6d",
                "file_part": 0,
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:42:00.167488Z"
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

更新單個 Chunk

更新單個資料區塊的內容或狀態。例如，可以手動修正切分不佳的文本，或禁用某個資料區塊使其不被檢索。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}

請求	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "text": "更新後的資料區塊常值內容...", "active": true }'`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
Content-Type `string`（必選） application/json
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。
chunk_id `string`（必選）資料區塊的唯一識別碼。
請求體（Request Body）
text `string`（可選）更新後的資料區塊常值內容。
active `bool`（可選）是否啟用該資料區塊。設定為 false 後，該資料區塊將不會被檢索到。

響應樣本

{
    "code": 200,
    "message": "Chunk update successful",
    "data": {
        "active": true,
        "text": "更新後的資料區塊常值內容...",
        "chunk_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
            "file_name": "EAS模型服務概述.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
            "token_count": 196,
            "doc_id": "2540b5414f2d422291cea3162eb8e1e0"
        },
        "file_id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_version": 0,
        "index": 0,
        "updated_at": "2026-02-27T07:42:00.167502Z",
        "status": "succeeded",
        "tenant_id": "__default_tenant_id__",
        "id": "e2b0d936158f4656a6cacb5ab639de6d",
        "file_part": 0,
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:42:00.167488Z"
    }
}

取消某個Chunk，不被檢索

同更新操作，active欄位設為false即可。

中繼資料管理

中繼資料可以為您的文檔增加結構化資訊，從而在檢索時實現更精確的過濾，例如：只檢索 IT 部門 2024 年之後發布的文檔。

知識庫級中繼資料欄位定義

為知識庫定義一個中繼資料欄位的 Schema，包括欄位ID、名稱、實值型別等。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

請求	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "kb_id": "kb9594e2d2d2744bf1acd4227a9202b90b", "name": "expire_period", "value_type": "datetime", "description": "產品保質期" }'`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
Content-Type `string`（必選） application/json
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
請求體（Request Body）
kb_id `string`（必選）知識庫的唯一識別碼。
name `string`（必選）欄位的顯示名稱。3～50 字元。
value_type `string`（必選）欄位的實值型別。enum類型，包含 string, number, datetime 三種類型。
description `string`（可選）欄位的描述資訊。

響應樣本

{
    "code": 200,
    "message": "Metadata created successfully.",
    "data": {
        "value_type": "datetime",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:49:19.964621Z",
        "name": "expire_period",
        "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
        "tenant_id": "__default_tenant_id__",
        "description": "產品保質期",
        "updated_at": "2026-02-27T07:49:19.964632Z"
    }
}

列出中繼資料

列出該知識庫下所有已定義的中繼資料欄位。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

請求	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。

響應樣本

{
    "code": 200,
    "message": "List metadata success.",
    "data": {
        "items": [
            {
                "value_type": "datetime",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:49:19.964621Z",
                "name": "expire_period",
                "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
                "tenant_id": "__default_tenant_id__",
                "description": "產品保質期",
                "updated_at": "2026-02-27T07:49:19.964632Z",
                "count": 0
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 20
    }
}

刪除中繼資料

刪除該知識庫下指定中繼資料欄位。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}

請求	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
metadata_id `string`（必選）中繼資料id。

響應樣本

{
    "code": 200,
    "message": "Delete metadata success.",
    "data": null
}

檔案級中繼資料綁定

為指定檔案綁定具體的中繼資料值。注意：此介面為覆蓋式更新，每次調用都會完全替換該檔案上的所有中繼資料。為避免資料丟失，推薦的操作流程是：先通過 GET 擷取檔案現有中繼資料，在本地修改後，再通過此介面提交完整的中繼資料列表。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata

請求	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "entries": [ {"name": "expire_period", "value": 1764574102000}, {"name": "category", "value": "food"}, {"name": "price", "value": 12} ] }'`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
Content-Type `string`（必選） application/json
URL路徑參數（Path parameters）
kb_id `string`（必選）知識庫的唯一識別碼。
file_id `string`（必選）檔案的唯一識別碼。
請求體（Request Body）
entries `array`（必選）中繼資料條目列表。屬性 name `string`（必選）中繼資料欄位的顯示名稱。需在知識庫層級定義過。 value `string/number`（必選）該欄位的具體值，類型需與定義時匹配。

響應樣本

{
    "code": 200,
    "message": "Set file metadata success.",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS模型服務概述.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:41:59.360291Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS模型服務概述.pdf",
            "file_name": "EAS模型服務概述.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "expire_period": 1764574102000,
            "category": "food"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772178119
    }
}

檢索 API

混合檢索（文本 + 向量 + 中繼資料過濾）

對指定的知識庫執行一次獨立的檢索操作，支援文本、向量和中繼資料過濾的混合檢索。

POST $EAS_SERVICE_URL/v1/retrieval

請求	`curl -X POST "$EAS_SERVICE_URL/v1/retrieval" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "query": "推薦系統", "knowledge_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4", "metadata_condition": { "conditions": [ {"name": "department", "value": "i", "comparison_operator": "start with"}, {"name": "age", "value": "23", "comparison_operator": "<"} ], "logical_operator": "and" }, "retrieval_setting": { "top_k": 2, "score_threshold": 0.4 } }'`
要求標頭（Headers）
Authorization `string`（必選）請求身份認證。EAS_TOKEN
Content-Type `string`（必選） application/json
請求體（Request Body）
query `string`（必選）用於檢索的查詢文本。
knowledge_id `string`（必選）要檢索的目標知識庫ID。
user_id `string`（可選）使用者的唯一標識，用於個人化或日誌追蹤。
metadata_condition `object`（可選）中繼資料過濾條件，包含 logical_operator（邏輯運算子：and/or）和 conditions（條件列表）。屬性 logical_operator `string`（可選）多個條件間的邏輯關係，預設為 `and`。可選值為 `and`和`or`。 conditions `array`（可選）條件列表。屬性 name `string`（必選）中繼資料欄位的ID。 value `string/number`（必選）用於比較的值。 comparison_operator `string`（必選）比較操作符。可取值 empty 等於空，沒有配置或值為空白 not empty 不等於空，已配置且有值 contains 包含某個值, 適用於字串類型 not contains 不包含某個值, 適用於字串類型 start with 以某個值開頭, 適用於字串類型 end with 以某個值結尾, 適用於字串類型 = 等於，適用於數值和datetime類型 ≠ 不等於，適用於數值和datetime類型 ≥ 大於等於,適用於數值和datetime類型 ≤ 小於等於,適用於數值和datetime類型 > 大於, 適用於數值和datetime類型 < 小於, 適用於數值和datetime類型
retrieval_setting `object`（可選）本次檢索的臨時配置，會覆蓋知識庫的預設配置。屬性 top_k `int`（可選）檢索返回的最相關資料區塊數量。 score_threshold `float`（可選）相似性得分閾值。

響應樣本

{
    "records": [
        {
            "content": "EasyRec是一個便於使用的推薦架構...",
            "score": 0.5892808330916407,
            "title": "EasyRec.txt",
            "metadata": {
                "file_name": "EasyRec.txt",
                "department": "it"
            }
        }
    ]
}

配置Code沙箱

建立或更新沙箱

請求	`curl -X POST "$EAS_SERVICE_URL/api/config/code_sandbox" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "type": "aliyun-fc", "aliyun_id": "your-aliyun-id", "interpreter_id": "your-interpreter-id", "enabled": true }'`
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
請求體（Request Body）
type `string`（必選）沙箱類型，當前僅支援阿里雲FC沙箱，取值`aliyun-fc`。
aliyun_id `string`（必選）阿里雲帳號ID。
interpreter_id `string`（必選）代碼解譯器ID。
enabled `bool`（必選）是否開啟沙箱功能。

查詢當前沙箱配置

curl -X GET "$EAS_SERVICE_URL/api/config/code_sandbox"

配置 FAQ

基礎路徑：/v1/config/apps（應用配置）、/v1/faq-retrieval（FAQ 檢索）

所有請求需攜帶鑒權（如 Authorization: Bearer YOUR_BEARER_TOKEN），並將 {EAS_SERVICE_URL} 替換為實際服務地址。

啟用並配置 FAQ

通過更新應用介面開啟 FAQ 並寫入配置。

PUT {EAS_SERVICE_URL}/v1/config/apps/{id}

請求	curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{id}" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "app_id": "your_app_id", "description": "應用描述", "model_id": "your_model_id", "kb_ids": [], "enable_faq": true, "faq_config": { "active": true, "similarity_threshold": 0.8, "embedding_model": "BAAI/bge-m3", "enable_question_in_retrieval": true, "enable_question_in_response": true, "enable_answer_in_retrieval": false, "enable_answer_in_response": true, "return_direct": false } }'
要求標頭（Headers）
Content-Type `string`（必選）請求內容類型。此參數必須設定為`application/json`。
Authorization `string`（必選）請求身份認證。EAS_TOKEN
URL路徑參數（Path parameters）
id `string`（必選）應用的主鍵 ID，可通過查詢應用介面獲得。
請求體（Request Body）
app_id `string`（必選）應用的 APP ID。
description `string`（可選）應用描述。
model_id `string`（必選）基模型。
kb_ids `array`（可選）應用使用的知識庫，可多選。
enable_faq `bool`（可選）是否啟用FAQ。
faq_config `object`（可選） FAQ 配置。屬性 active `bool`（可選）是否啟用 FAQ 配置。 similarity_threshold `float`（可選）相似性閾值，建議 0.8～1.0。 embedding_model `string`（可選） Embedding 模型 ID。 enable_question_in_retrieval `bool`（可選）問題是否參與檢索。 enable_question_in_response `bool`（可選）響應中是否包含問題。 enable_answer_in_retrieval `bool`（可選）答案是否參與檢索。 enable_answer_in_response `bool` （可選）響應中是否包含答案。 return_direct `bool`（可選）是否直接返回工具結果（不經過 LLM）。

查詢應用

curl -X GET "$EAS_SERVICE_URL/v1/config/apps?app_id=your_app_id" \
  -H "Authorization: Bearer $EAS_TOKEN"

其中：app_id 擷取方式如下。在控制台的應用配置頁面，選擇Chat應用頁簽，查看App ID必要欄位擷取應用ID值（如chatbot），將其作為請求中app_id參數的值。

建立單條 FAQ

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "如何重設密碼？",
    "answer": "請點擊登入頁的「忘記密碼」按提示操作。",
    "active": true
  }'

查詢 FAQ 列表（分頁）

curl -X GET "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs?page=1&size=100" \
  -H "Authorization: Bearer $EAS_TOKEN"

更新單條 FAQ

curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "如何修改密碼？",
    "answer": "登入後進入「帳號設定」-「安全」中修改。",
    "active": true
  }'

刪除單條 FAQ

curl -X DELETE "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN"

批量上傳 FAQ 檔案（Excel）

使用 multipart/form-data：上傳欄位名為 files（可多檔案），可選表頭與列映射 table_config（JSON 字串）。支援 .xlsx、.xls。

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faq-files" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -F 'files=@/path/to/faq.xlsx' \
  -F 'table_config={"header_index_max":0,"question_column_index":0,"answer_column_index":1}'

table_config 說明：

header_index_max ：表頭行數（0 表示第一行為表頭）；
question_column_index ：問題列索引（從 0 開始）；
answer_column_index：答案列索引。

FAQ 檢索（獨立調用）

不經過對話，直接按問題檢索 FAQ 結果：

curl -X POST "$EAS_SERVICE_URL/v1/faq-retrieval" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatapp_id": "your_app_id",
    "query": "使用者輸入的問題"
  }'

可選請求欄位：user_id、retrieval_setting（如 top_k、similarity_threshold 等）。未傳 retrieval_setting 時使用該應用 FAQ 配置中的預設值。

準備工作：擷取服務訪問地址和Token

Chat API

知識庫管理員

建立知識庫

請求

要求標頭（Headers）

請求體（Request Body）

響應樣本

擷取知識庫列表

請求

要求標頭（Headers）

URL查詢參數（Query parameters）

響應樣本

擷取指定知識庫（通過kb_id）

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

響應樣本

修改知識庫

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

請求體（Request Body）

響應樣本

刪除指定知識庫

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

響應樣本

檔案管理

上傳檔案

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

請求體參數（Request Body）

響應樣本

列出檔案

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

URL查詢參數（Query parameters）

響應樣本

擷取單個檔案資訊

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

響應樣本

重新處理檔案

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

響應樣本

刪除檔案

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

響應樣本

資料分塊管理

查看檔案分塊

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

URL查詢參數（Query parameters）

響應樣本

更新單個 Chunk

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

請求體（Request Body）

響應樣本

取消某個Chunk，不被檢索

中繼資料管理

知識庫級中繼資料欄位定義

請求

要求標頭（Headers）

URL路徑參數（Path parameters）

請求體（Request Body）

響應樣本

列出中繼資料

請求