AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 人工智能平台 PAI 实践教程 RAG RAG API接口说明 适用于v0.4.x版本

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

更新时间：
产品详情
我的收藏

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

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

通过API接口调用RAG服务前，需要获取RAG服务的访问地址（EAS_SERVICE_URL）和认证令牌（EAS_TOKEN）。所有 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

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

# {EAS_SERVICE_URL} 和 {EAS_TOKEN} 替换为真实的路径和token
EAS_ENDPOINT = "{EAS_SERVICE_URL}"
EAS_TOKEN = "{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

功能描述: 创建一个新的知识库，并可以指定其数据分块、嵌入和检索等配置。

请求体 (application/json)

字段

类型

是否必填

描述

name

String

是

知识库名称。

description

String

否

知识库的描述信息。

chunk_config

Object

否

数据分块配置。

chunk_config.parser_type

String

否

解析器类型。

chunk_config.separator

String

否

自定义分隔符。

chunk_config.chunk_size

Integer

否

每个数据块的最大长度（单位：字符）。

chunk_config.chunk_overlap

Integer

否

相邻数据块之间的重叠长度（单位：字符）。

embedding_model

String

否

嵌入模型的名称或路径。支持本地或远程模型。

retrieval_config

Object

否

检索策略配置。

retrieval_config.retrieval_mode

String

否

检索模式。

retrieval_config.top_k

Integer

否

检索返回的最相关数据块数量。

retrieval_config.similarity_threshold

Float

否

相似度得分阈值，低于此值的结果将被过滤。

retrieval_config.enable_rerank

Boolean

否

是否启用重排模型以优化检索结果。

retrieval_config.rerank_model

String

否

重排模型的名称或路径。

重要

需先在PAI-RAG的WebUI中通过Settings配置好Reranker模型，才可使用。

retrieval_config.vector_weight

Float

否

在混合检索中，向量检索的权重。

请求示例

{
    "name": "example_kb",
    "description": "这是一个示例知识库",
    "chunk_config": {
        "parser_type": "Sentence",
        "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
    }
}

响应示例

{
    "code": 200,
    "message": "知识库创建成功。",
    "data": {
        "id": "kb4451867a6d0f4166babddb7a048a311d",
        "name": "example_kb",
        "description": "这是一个示例知识库",
        "created_at": "2025-11-12T02:18:48.737966",
        "updated_at": "2025-11-12T02:18:48.737976",
        "embedding_model": "BAAI/bge-m3",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "Sentence",
            "separator": "\n\n"
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker"
        }
    }
}

获取知识库列表

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

功能描述: 获取当前服务下的知识库列表，支持分页。

查询参数

参数名

类型

是否必填

描述

page

Integer

否

页码，默认值为 1。

size

Integer

否

每页返回的数量，默认值为 10，上限为 1000。

响应示例

{
    "code": 200,
    "message": "获取知识库列表成功",
    "data": {
        "items": [
            {
                "name": "example_kb知识库",
                "created_at": "2025-11-12T02:18:48.737966",
                "updated_at": "2025-11-12T02:18:48.737976",
                "description": "示例",
                "id": "kb4451867a6d0f4166babddb7a048a311d",
                "embedding_model": "BAAI/bge-m3",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "Sentence",
                    "separator": "\n\n"
                },
                "retrieval_config": {
                    "retrieval_mode": "hybrid",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": true,
                    "rerank_model": "qwen3-reranker"
                }
            },
            {
                "name": "测试",
                "created_at": "2025-11-11T05:25:30.432619",
                "updated_at": "2025-11-11T05:25:30.432629",
                "description": "测试数据",
                "id": "kbd743947b6b2648a98b020d208ccfbd45",
                "embedding_model": "BAAI/bge-m3",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "Sentence",
                    "separator": "\n\n"
                },
                "retrieval_config": {
                    "retrieval_mode": "hybrid",
                    "top_k": 5,
                    "similarity_threshold": 0.3,
                    "vector_weight": 0.7,
                    "enable_rerank": false,
                    "rerank_model": ""
                }
            }
        ],
        "total": 2,
        "pages": 1,
        "page": 1,
        "size": 6
    }
}

获取指定知识库（通过kb_id）

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

功能描述: 获取指定 ID 的知识库的详细信息。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

响应示例

{
    "code": 200,
    "message": "查询知识库成功。",
    "data": {
        "name": "example_kb知识库",
        "created_at": "2025-11-12T02:18:48.737966",
        "updated_at": "2025-11-12T02:18:48.737976",
        "description": "示例",
        "id": "kb4451867a6d0f4166babddb7a048a311d",
        "embedding_model": "BAAI/bge-m3",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "Sentence",
            "separator": "\n\n"
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker"
        }
    }
}

修改知识库

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

功能描述: 修改一个已存在的知识库。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

请求体 (application/json)

同创建知识库。

请求示例

{
    "name": "example_kb",
    "description": "示例",
    "id": "kb4451867a6d0f4166babddb7a048a311d",
    "embedding_model": "BAAI/bge-m3",
    "chunk_config": {
        "chunk_size": 1000,
        "chunk_overlap": 50,
        "parser_type": "Sentence",
        "separator": "\n\n"
    },
    "retrieval_config": {
        "retrieval_mode": "hybrid",
        "top_k": 5,
        "similarity_threshold": 0.2,
        "vector_weight": 0.7,
        "enable_rerank": true,
        "rerank_model": "qwen3-reranker"
    }
}

响应示例

{
    "code": 200,
    "message": "更新知识库成功。",
    "data": {
        "name": "example_kb",
        "created_at": "2025-11-12T02:18:48.737966",
        "updated_at": "2025-11-12T02:18:48.737976",
        "description": "示例",
        "id": "kb4451867a6d0f4166babddb7a048a311d",
        "embedding_model": "BAAI/bge-m3",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "Sentence",
            "separator": "\n\n"
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker"
        }
    }
}

删除指定知识库

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

功能描述: 删除一个指定的知识库及其包含的所有文件和索引。此操作不可逆，请谨慎使用。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

响应示例

{
    "code": 200,
    "message": "知识库'kb4451867a6d0f4166babddb7a048a311d'删除成功。",
    "data": null
}

文件管理

上传文件

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

功能描述: 向指定知识库上传一个或多个文件。这是一个异步接口，会立即返回文件信息，并在后台进行解析和索引。支持的文件格式包括 PDF、DOCX、TXT 等。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

请求体 (multipart/form-data)

字段

类型

是否必填

描述

files

File

是

要上传的文件（支持 PDF/DOCX/TXT 等）。可以一次上传多个。

响应示例

{
    "code": 200,
    "message": "文件上传成功",
    "data": [
        {
            "id": "ee2726b4398045918c51ca4ccabb1941",
            "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
            "message_id": "tmp-1762914524",
            "file_content": "",
            "file_content_length": 0,
            "file_name": "EasyRec.txt",
            "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
            "file_extension": ".txt",
            "file_size": 1361,
            "file_md5": "6119e1bd860c5be2b528c2c6b0e89422",
            "file_metadata": {
                "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
                "file_name": "EasyRec.txt",
                "file_size": 1361,
                "file_extension": ".txt"
            },
            "file_source": null,
            "file_version": 1762914523,
            "status": "pending",
            "failed_reason": null,
            "active": true,
            "created_at": "2025-11-12T02:28:44.588010",
            "updated_at": "2025-11-12T02:28:44.588025"
        }
    ]
}

列出文件

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

功能描述: 列出指定知识库中的文件，支持按文件名和状态进行筛选和分页。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

查询参数

参数名

类型

是否必填

描述

query

String

否

根据文件名进行模糊匹配。

status

String

否

根据文件处理状态筛选。不传为全部，可选值：

  • pending： 等待

  • succeeded ：成功

  • failed ：失败

  • persisting ：索引中

  • parsing ：解析中

page

Integer

否

页码，默认值为 1。

size

Integer

否

每页返回的数量，默认值为 10。

响应示例

{
    "code": 200,
    "message": "获取文件列表成功",
    "data": {
        "items": [
            {
                "id": "ee2726b4398045918c51ca4ccabb1941",
                "file_name": "EasyRec.txt",
                "status": "succeeded",
                // ... 其他字段
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

获取单个文件信息

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

功能描述: 获取单个文件的详细信息，常用于轮询文件处理状态。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

file_id

String

是

文件的唯一标识符。

响应示例

{
    "code": 200,
    "message": "文件入队成功。",
    "data": {
        "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
        "id": "ee2726b4398045918c51ca4ccabb1941",
        "message_id": "tmp-1762914524",
        "file_content_length": 0,
        "file_name": "EasyRec.txt",
        "file_extension": ".txt",
        "file_md5": "6119e1bd860c5be2b528c2c6b0e89422",
        "status": "pending",
        "active": true,
        "updated_at": "2025-11-12T02:28:44.588025",
        "file_content": "",
        "file_source": null,
        "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
        "file_size": 1361,
        "file_version": 1762914861,
        "failed_reason": null,
        "created_at": "2025-11-12T02:28:44.588010",
        "file_metadata": {
            "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
            "file_name": "EasyRec.txt",
            "file_size": 1361,
            "file_extension": ".txt"
        }
    }
}

重新处理文件

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

功能描述: 触发对一个文件（例如处理失败或内容已更新的文件）的重新处理。这是一个异步操作，会创建一个新的处理任务，并将文件状态重置为 pending。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

file_id

String

是

文件的唯一标识符。

请求体: 空

响应示例

{
    "code": 200,
    "message": "文件入队成功。",
    "data": {
        "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
        "id": "ee2726b4398045918c51ca4ccabb1941",
        "message_id": "tmp-1762914524",
        "file_content_length": 0,
        "file_name": "EasyRec.txt",
        "file_extension": ".txt",
        "file_md5": "6119e1bd860c5be2b528c2c6b0e89422",
        "status": "pending",
        "active": true,
        "updated_at": "2025-11-12T02:28:44.588025",
        "file_content": "",
        "file_source": null,
        "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
        "file_size": 1361,
        "file_version": 1762914861,
        "failed_reason": null,
        "created_at": "2025-11-12T02:28:44.588010",
        "file_metadata": {
            "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
            "file_name": "EasyRec.txt",
            "file_size": 1361,
            "file_extension": ".txt"
        }
    }
}

删除文件

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

功能描述: 从知识库中删除一个指定的文件及其关联的数据块和索引。

路径参数

参数名

类型

是否必填

描述

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

功能描述: 查看指定文件被切分后的数据块列表，支持分页。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

file_id

String

是

文件的唯一标识符。

查询参数

参数名

类型

是否必填

描述

page

Integer

否

页码，默认值为 1。

size

Integer

否

每页返回的数量，默认值为 10。

响应示例

{
    "code": 200,
    "message": "获取切片列表成功",
    "data": {
        "items": [
            {
                "status": "succeeded",
                "text": "EasyRec是一个易于使用的推荐框架¶\nEasyRec 实现了常见推荐任务中使用的最先进的机器学习模型：候选生成（匹配）、评分（排名）和多任务学习。 它通过简单的配置和超参数调整（HPO）提高了生成高性能模型的效率。\n\nEasyRec视频介绍\n为什么选择 EasyRec？¶\n到处运行¶\nMaxCompute / 数据科学 / DLC / 本地\nTF1.12-1.15 / TF2.x / PAI-TF\n多样的输入数据¶\nMaxCompute表\nHDFS 文件\n操作系统文件\n卡夫卡流\n本地 CSV\n\n配置简单¶\n灵活的功能配置和简单的模型配置\n高效、鲁棒的特征生成[淘宝使用]\n漂亮的网络界面正在开发中\n\n它很聪明¶\nEarlyStop / 最佳检查站保护程序\n超参数搜索/AutoFeatureCross\n开发中：NAS、知识蒸馏、多模式\n\n规模大、部署方便¶\n支持大规模嵌入，增量保存\n许多并行策略：ParameterServer、Mirrored、MultiWorker\n轻松部署到 EAS：自动扩展、轻松监控\n一致性保证：训练和服务\n\n多种模型\nDSSM / MIND / DropoutNet / CoMetricLearningI2I / PDN\nW&D / DeepFM / MultiTower / DCN / DIN / BST\nMMoE / ESMM / DBMTL / PLE\nCMBF / 联合\n\n易于定制¶\n易于实现定制模型\n无需关心数据管道\n快速向量检索¶\n在分布式环境中运行向量的 knn 算法\n\n欢迎加入【EasyRec推荐算法交流群】，钉钉群号 : 32260796",
                "active": true,
                "file_id": "be479a8546d94cde91b4c2edb1a97ac6",
                "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
                "created_at": "2025-11-12T02:41:38.094799",
                "updated_at": "2025-11-12T02:41:38.094813",
                "id": "f5634550fa254956a9cc105482dc236d",
                "chunk_metadata": {
                    "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
                    "file_name": "EasyRec.txt",
                    "file_size": 1361,
                    "file_extension": ".txt",
                    "doc_id": "be479a8546d94cde91b4c2edb1a97ac6",
                    "images_info": []
                },
                "file_part": 0,
                "file_version": 0,
                "index": 0
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 8
    }
}

更新单个 Chunk

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

功能描述: 更新单个数据块的内容或状态。例如，可以手动修正切分不佳的文本，或禁用某个数据块使其不被检索。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

file_id

String

是

文件的唯一标识符。

chunk_id

String

是

数据块的唯一标识符。

请求体 (application/json)

字段

类型

是否必填

描述

text

String

否

更新后的数据块文本内容。

active

Boolean

否

是否启用该数据块。设置为 false 后，该数据块将不会被检索到。

请求示例

{
    "status": "succeeded",
    "text": "EasyRec是一个易于使用的推荐框架¶\nEasyRec 实现了常见推荐任务中使用的最先进的机器学习模型：候选生成（匹配）、评分（排名）和多任务学习。 它通过简单的配置和超参数调整（HPO）提高了生成高性能模型的效率。\n作者：费跃\n\nEasyRec视频介绍\n为什么选择 EasyRec？¶\n到处运行¶\nMaxCompute / 数据科学 / DLC / 本地\nTF1.12-1.15 / TF2.x / PAI-TF\n多样的输入数据¶\nMaxCompute表\nHDFS 文件\n操作系统文件\n卡夫卡流\n本地 CSV\n\n配置简单¶\n灵活的功能配置和简单的模型配置\n高效、鲁棒的特征生成[淘宝使用]\n漂亮的网络界面正在开发中\n\n它很聪明¶\nEarlyStop / 最佳检查站保护程序\n超参数搜索/AutoFeatureCross\n开发中：NAS、知识蒸馏、多模式\n\n规模大、部署方便¶\n支持大规模嵌入，增量保存\n许多并行策略：ParameterServer、Mirrored、MultiWorker\n轻松部署到 EAS：自动扩展、轻松监控\n一致性保证：训练和服务\n\n多种模型\nDSSM / MIND / DropoutNet / CoMetricLearningI2I / PDN\nW&D / DeepFM / MultiTower / DCN / DIN / BST\nMMoE / ESMM / DBMTL / PLE\nCMBF / 联合\n\n易于定制¶\n易于实现定制模型\n无需关心数据管道\n快速向量检索¶\n在分布式环境中运行向量的 knn 算法\n\n欢迎加入【EasyRec推荐算法交流群】，钉钉群号 : 32260796",
    "active": true,
    "file_id": "be479a8546d94cde91b4c2edb1a97ac6",
    "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
    "created_at": "2025-11-12T02:41:38.094799",
    "updated_at": "2025-11-12T02:41:38.094813",
    "id": "f5634550fa254956a9cc105482dc236d",
    "chunk_metadata": {
        "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
        "file_name": "EasyRec.txt",
        "file_size": 1361,
        "file_extension": ".txt",
        "doc_id": "be479a8546d94cde91b4c2edb1a97ac6",
        "images_info": []
    },
    "file_part": 0,
    "file_version": 0,
    "index": 0
}

响应示例

{
    "code": 200,
    "message": "更新知识库切片成功。",
    "data": {
        "status": "succeeded",
        "text": "EasyRec是一个易于使用的推荐框架¶\nEasyRec 实现了常见推荐任务中使用的最先进的机器学习模型：候选生成（匹配）、评分（排名）和多任务学习。 它通过简单的配置和超参数调整（HPO）提高了生成高性能模型的效率。\n作者：费跃\n\nEasyRec视频介绍\n为什么选择 EasyRec？¶\n到处运行¶\nMaxCompute / 数据科学 / DLC / 本地\nTF1.12-1.15 / TF2.x / PAI-TF\n多样的输入数据¶\nMaxCompute表\nHDFS 文件\n操作系统文件\n卡夫卡流\n本地 CSV\n\n配置简单¶\n灵活的功能配置和简单的模型配置\n高效、鲁棒的特征生成[淘宝使用]\n漂亮的网络界面正在开发中\n\n它很聪明¶\nEarlyStop / 最佳检查站保护程序\n超参数搜索/AutoFeatureCross\n开发中：NAS、知识蒸馏、多模式\n\n规模大、部署方便¶\n支持大规模嵌入，增量保存\n许多并行策略：ParameterServer、Mirrored、MultiWorker\n轻松部署到 EAS：自动扩展、轻松监控\n一致性保证：训练和服务\n\n多种模型\nDSSM / MIND / DropoutNet / CoMetricLearningI2I / PDN\nW&D / DeepFM / MultiTower / DCN / DIN / BST\nMMoE / ESMM / DBMTL / PLE\nCMBF / 联合\n\n易于定制¶\n易于实现定制模型\n无需关心数据管道\n快速向量检索¶\n在分布式环境中运行向量的 knn 算法\n\n欢迎加入【EasyRec推荐算法交流群】，钉钉群号 : 32260796",
        "active": true,
        "file_id": "be479a8546d94cde91b4c2edb1a97ac6",
        "kb_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
        "created_at": "2025-11-12T02:41:38.094799",
        "updated_at": "2025-11-12T02:41:38.094813",
        "id": "f5634550fa254956a9cc105482dc236d",
        "chunk_metadata": {
            "file_path": "kbdeec6a87e7b342b6a0da7e67a171fbb4/docs/EasyRec.txt",
            "file_name": "EasyRec.txt",
            "file_size": 1361,
            "file_extension": ".txt",
            "doc_id": "be479a8546d94cde91b4c2edb1a97ac6"
        },
        "file_part": 0,
        "file_version": 0,
        "index": 0
    }
}

取消某个Chunk，不被检索

同更新操作，active字段设为false即可。

元数据管理

元数据可以为您的文档增加结构化信息，从而在检索时实现更精确的过滤，例如“只检索 IT 部门 2024 年之后发布的文档”。

知识库级元数据字段定义

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

功能描述: 为知识库定义一个元数据字段的 Schema，包括字段ID、名称、值类型等。要列出该知识库下所有已定义的元数据字段，请使用 GET 方法访问同一路径。

路径参数

参数名

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

请求体 (application/json)

字段

类型

是否必填

描述

kb_id

String

是

知识库的唯一标识符。

id

String

是

字段的唯一ID，长度必须在3到50个字符之间。

name

String

是

字段的显示名称。

value_type

String

是

字段的值类型。enum类型，包含string, number, datetime三种类型。

description

String

否

字段的描述信息。

请求示例

{
  "kb_id":"kbdeec6a87e7b342b6a0da7e67a171fbb4",
  "id": "department",
  "name": "所属部门",
  "value_type": "string",
  "description": "文件所属的业务部门"
}

响应示例

{
    "code": 200,
    "message": "元数据创建成功。",
    "data": {
        "kb_id": "kbbb029f405c2840fb977410b54f63d26c",
        "name": "所属部门",
        "description": "文件所属的业务部门",
        "updated_at": "2025-11-21T05:49:48.135038",
        "id": "department",
        "value_type": "string",
        "created_at": "2025-11-21T05:49:48.135020"
    }
}

检索 API

混合检索（文本 + 向量 + 元数据过滤）

POST {EAS_SERVICE_URL}/v1/retrieval

功能描述: 对指定的知识库执行一次独立的检索操作，支持文本、向量和元数据过滤的混合检索。

请求体 (application/json)

字段

类型

是否必填

描述

query

String

是

用于检索的查询文本。

knowledge_id

String

是

要检索的目标知识库ID。

user_id

String

否

用户的唯一标识，用于个性化或日志追踪。

metadata_condition

Object

否

元数据过滤条件。

metadata_condition.logical_operator

String

否

多个条件间的逻辑关系，默认为 and。可选值为 and和or。

metadata_condition.conditions

Array

否

条件列表。

conditions[].name

String

是

元数据字段的ID。

conditions[].value

String/Number

是

用于比较的值。

conditions[].comparison_operator

String

是

比较操作符。

可取值

  • empty 等于空，没有配置或值为空

  • not empty 不等于空，已配置且有值

  • contains 包含某个值, 适用于字符串类型

  • not contains 不包含某个值, 适用于字符串类型

  • start with 以某个值开头, 适用于字符串类型

  • end with 以某个值结尾, 适用于字符串类型

  • = 等于，适用于数值和datetime类型

  • ≠ 不等于，适用于数值和datetime类型

  • ≥ 大于等于,适用于数值和datetime类型

  • ≤ 小于等于,适用于数值和datetime类型

  • > 大于, 适用于数值和datetime类型

  • < 小于, 适用于数值和datetime类型

retrieval_setting

Object

否

本次检索的临时配置，会覆盖知识库的默认配置。

retrieval_setting.top_k

Integer

否

检索返回的最相关数据块数量。

retrieval_setting.score_threshold

Float

否

相似度得分阈值。

请求示例

{
    "query": "推荐系统",
    "knowledge_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4",
    "metadata_condition": {
        "conditions": [
            {
                "name": "department",
                "value": "i",
                "comparison_operator": "start with"
            }
        ],
        "logical_operator": "and"
    },
    "retrieval_setting": {
        "top_k": 2,
        "score_threshold": 0.4
    }
}

响应体

字段

类型

描述

records

Array

检索到的数据块记录列表。

records[].content

String

数据块的文本内容。

records[].score

Float

相关性得分（通常在0到1之间），分数越高表示相关性越强。

records[].title

String

数据块所属的源文件名。

records[].metadata

Object

数据块关联的元数据。

响应示例

{
    "records": [
        {
            "content": "EasyRec是一个易于使用的推荐框架...",
            "score": 0.5892808330916407,
            "title": "EasyRec.txt",
            "metadata": {
                "file_name": "EasyRec.txt",
                "department": "it",
                // ... 其他元数据
            }
        }
    ]
}
上一篇：RAG API接口说明下一篇：适用于v0.3.0-v0.3.4版本镜像