AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

PAI-RAG 服务 API 参考 (v0.4.x)

更新时间：
复制为 MD 格式
产品详情
我的收藏

本文档适用于 v0.4.x 版本的 PAI-RAG 服务，提供完整的 API 接口定义、请求示例与核心概念说明，旨在帮助开发者快速、高效地将 PAI-RAG 的能力集成到自己的应用中。

准备工作：获取服务访问地址和Token

通过API接口调用RAG服务前，需要获取RAG服务的访问地址和认证令牌。所有 API 请求都需要在 HTTP Authorization 中携带EAS_TOKEN。

在下文API接口说明中出现的$EAS_SERVICE_URL和$EAS_TOKEN是环境变量，使用前需要先设置。获取方式如下：

  1. 登录PAI控制台，在页面上方选择目标地域，并在右侧选择目标工作空间，然后单击进入EAS。

  2. 单击目标服务名称，然后在基本信息区域，单击查看调用信息。

  3. 在调用信息页面，获取公网/VPC调用地址（EAS_SERVICE_URL）和Token（EAS_TOKEN）。

    重要

    • 请将EAS_SERVICE_URL末尾的斜杠（/）删除。

    • 使用公网调用地址：调用客户端支持访问公网。

    • 使用VPC调用地址：调用客户端必须与RAG服务位于同一个专有网络内。

    image

获取到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 从下图获取。image

创建单条 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 配置中的默认值。

上一篇：RAG版本说明下一篇：通过知识库加密搭建安全增强的RAG应用