RAGFlow 知识图谱 API 参考手册
完整的 RAGFlow GraphRAG API 交互式文档，涵盖认证、数据集、文档、检索、对话及知识图谱构建全流程
RESTful API 可交互测试 GraphRAG 代码即用
API 测试器配置
请确保 RAGFlow 服务已启动且允许跨域访问 (CORS)。若遇到跨域问题，请检查服务端配置或使用浏览器插件临时禁用 CORS 限制。
认证与配置
API Key 管理与 Bearer Token 认证机制，所有 API 请求均需携带有效的 API Key
认证方式：RAGFlow 使用 Bearer Token 认证。在请求头中添加
Authorization: Bearer <your-api-key> 即可。API Key 可通过 RAGFlow Web 界面（系统设置 → API 密钥）获取，也可通过下方 API 创建。POST/api/v1/tokens创建API密钥
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 必填 | Token 名称，用于标识此 API 密钥 |
响应示例
JSON Response
{
"code": 0,
"data": {
"token": "ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm",
"name": "my-api-key",
"create_time": 1715000000
}
}
cURL
curl -X POST "http://localhost:80/api/v1/tokens" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "my-api-key"}'
Python
import requests
url = "http://localhost:80/api/v1/tokens"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "my-api-key"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/tokens列出API密钥
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 可选 | 页码，默认 1 |
| page_size | integer | 可选 | 每页数量，默认 30 |
响应示例
JSON Response
{
"code": 0,
"data": [
{
"token": "ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm",
"name": "my-api-key",
"create_time": 1715000000
}
]
}
cURL
curl -X GET "http://localhost:80/api/v1/tokens?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
url = "http://localhost:80/api/v1/tokens"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
DELETE/api/v1/tokens/{token}删除API密钥
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| token | string | 必填 | 要删除的 API 密钥 Token 值 |
响应示例
JSON Response
{
"code": 0
}
cURL
curl -X DELETE "http://localhost:80/api/v1/tokens/ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
token = "ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
url = f"http://localhost:80/api/v1/tokens/{token}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
response = requests.delete(url, headers=headers)
print(response.json())
数据集管理
数据集是 RAGFlow 的核心容器，创建数据集时可配置 GraphRAG 参数以启用知识图谱功能
知识图谱关联：数据集是知识图谱的载体。创建数据集时通过
chunk_method 设置为 "graphrag"，并配置 graphrag 参数即可启用知识图谱构建。解析文档后，系统将自动提取实体、关系并构建图谱。POST/api/v1/datasets创建数据集
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 必填 | 数据集名称 |
| chunk_method | string | 可选 | 分块方法，启用图谱设为 "graphrag" |
| graphrag.entity_types | array | 可选 | 实体类型列表，如 ["Organization","Person","Geo","Event","Category"] |
| graphrag.method | string | 可选 | 图谱构建方法："light"（轻量）或 "general"（通用） |
| graphrag.community | boolean | 可选 | 是否启用社区检测，默认 false |
| graphrag.resolution | boolean | 可选 | 是否启用实体消解（合并相同实体），默认 false |
| embedding_model | string | 可选 | Embedding 模型名称 |
| permission | string | 可选 | 权限："me" 或 "team" |
响应示例
JSON Response
{
"code": 0,
"data": {
"id": "ds-abc123",
"name": "knowledge-graph-ds",
"chunk_method": "graphrag",
"graphrag": {
"entity_types": [
"Organization",
"Person",
"Geo",
"Event",
"Category"
],
"method": "light",
"community": false,
"resolution": false
}
}
}
cURL
curl -X POST "http://localhost:80/api/v1/datasets" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "knowledge-graph-ds", "chunk_method": "graphrag", "graphrag": {"entity_types": ["Organization", "Person", "Geo", "Event", "Category"], "method": "light", "community": false, "resolution": false}}'
Python
import requests
url = "http://localhost:80/api/v1/datasets"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {
"name": "knowledge-graph-ds",
"chunk_method": "graphrag",
"graphrag": {
"entity_types": ["Organization", "Person", "Geo", "Event", "Category"],
"method": "light",
"community": False,
"resolution": False
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/datasets列出数据集
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 可选 | 页码，默认 1 |
| page_size | integer | 可选 | 每页数量，默认 30 |
| orderby | string | 可选 | 排序字段 |
| desc | boolean | 可选 | 是否降序 |
| name | string | 可选 | 按名称过滤 |
响应示例
JSON Response
{
"code": 0,
"data": [
{
"id": "ds-abc123",
"name": "knowledge-graph-ds",
"chunk_method": "graphrag",
"document_count": 5,
"chunk_num": 128
}
]
}
cURL
curl -X GET "http://localhost:80/api/v1/datasets?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
url = "http://localhost:80/api/v1/datasets"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
PUT/api/v1/datasets/{dataset_id}更新数据集
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dataset_id | string | 必填 | 数据集 ID |
| name | string | 可选 | 数据集名称 |
| chunk_method | string | 可选 | 分块方法 |
| graphrag | object | 可选 | GraphRAG 配置（同创建接口） |
| embedding_model | string | 可选 | Embedding 模型 |
响应示例
JSON Response
{
"code": 0,
"data": {
"id": "ds-abc123",
"name": "updated-ds-name",
"chunk_method": "graphrag"
}
}
cURL
curl -X PUT "http://localhost:80/api/v1/datasets/ds-abc123" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "updated-ds-name", "graphrag": {"community": true, "resolution": true}}'
Python
import requests
dataset_id = "ds-abc123"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "updated-ds-name", "graphrag": {"community": True, "resolution": True}}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
DELETE/api/v1/datasets删除数据集
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ids | array | 必填 | 要删除的数据集 ID 列表 |
响应示例
JSON Response
{
"code": 0
}
cURL
curl -X DELETE "http://localhost:80/api/v1/datasets" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"ids": ["ds-abc123", "ds-def456"]}'
Python
import requests
url = "http://localhost:80/api/v1/datasets"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"ids": ["ds-abc123", "ds-def456"]}
response = requests.delete(url, json=payload, headers=headers)
print(response.json())
文档管理
上传、解析文档，触发知识图谱构建。文档解析是 GraphRAG 构建图谱的核心步骤
POST/api/v1/datasets/{dataset_id}/documents上传文档
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dataset_id | string | 必填 | 数据集 ID |
| file | file | 必填 | 上传的文件（支持 PDF/DOCX/TXT/MD 等） |
| chunk_method | string | 可选 | 覆盖数据集的分块方法 |
响应示例
JSON Response
{
"code": 0,
"data": [
{
"id": "doc-xyz789",
"name": "report.pdf",
"dataset_id": "ds-abc123",
"status": 0,
"chunk_method": "graphrag"
}
]
}
cURL
curl -X POST "http://localhost:80/api/v1/datasets/ds-abc123/documents" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-F "file=@/path/to/report.pdf"
Python
import requests
dataset_id = "ds-abc123"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
files = {"file": open("/path/to/report.pdf", "rb")}
response = requests.post(url, headers=headers, files=files)
print(response.json())
GET/api/v1/datasets/{dataset_id}/documents列出文档
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dataset_id | string | 必填 | 数据集 ID |
| page | integer | 可选 | 页码 |
| page_size | integer | 可选 | 每页数量 |
| keywords | string | 可选 | 关键词搜索 |
响应示例
JSON Response
{
"code": 0,
"data": [
{
"id": "doc-xyz789",
"name": "report.pdf",
"status": 1,
"progress": 100,
"chunk_num": 42
}
]
}
cURL
curl -X GET "http://localhost:80/api/v1/datasets/ds-abc123/documents?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
dataset_id = "ds-abc123"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
GET/api/v1/datasets/{dataset_id}/documents/{document_id}下载文档
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dataset_id | string | 必填 | 数据集 ID |
| document_id | string | 必填 | 文档 ID |
cURL
curl -X GET "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-o "downloaded_file.pdf"
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
response = requests.get(url, headers=headers)
with open("downloaded_file.pdf", "wb") as f:
f.write(response.content)
DELETE/api/v1/datasets/{dataset_id}/documents删除文档
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ids | array | 必填 | 要删除的文档 ID 列表 |
响应示例
JSON Response
{
"code": 0
}
cURL
curl -X DELETE "http://localhost:80/api/v1/datasets/ds-abc123/documents" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"ids": ["doc-xyz789"]}'
Python
import requests
dataset_id = "ds-abc123"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"ids": ["doc-xyz789"]}
response = requests.delete(url, json=payload, headers=headers)
print(response.json())
POST/api/v1/datasets/{dataset_id}/documents/{document_id}/parse解析文档触发图谱构建
核心步骤：对于 GraphRAG 数据集，调用此 API 将触发文档解析并自动构建知识图谱，包括实体抽取、关系提取和图谱存储。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dataset_id | string | 必填 | 数据集 ID |
| document_id | string | 必填 | 文档 ID |
响应示例
JSON Response
{
"code": 0,
"data": {
"id": "doc-xyz789",
"status": 1,
"progress": 0
}
}
cURL
curl -X POST "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789/parse" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}/parse"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
response = requests.post(url, headers=headers)
print(response.json())
POST/api/v1/datasets/{dataset_id}/chunks停止解析
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| document_ids | array | 必填 | 要停止解析的文档 ID 列表 |
cURL
curl -X POST "http://localhost:80/api/v1/datasets/ds-abc123/chunks" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"document_ids": ["doc-xyz789"]}'
Python
import requests
dataset_id = "ds-abc123"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/chunks"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"document_ids": ["doc-xyz789"]}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
块管理
管理文档解析后生成的文本块，每个块可能关联图谱中的实体与关系
POST/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks添加块
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 必填 | 块文本内容 |
| important_keywords | array | 可选 | 关键关键词列表 |
| question | string | 可选 | 与此块关联的问题 |
响应示例
JSON Response
{
"code": 0,
"data": {
"chunk_id": "chunk-aaa111",
"content": "RAGFlow 是一个开源的 RAG 引擎...",
"important_keywords": [
"RAGFlow",
"RAG"
]
}
}
cURL
curl -X POST "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789/chunks" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"content": "RAGFlow 是一个开源的 RAG 引擎", "important_keywords": ["RAGFlow", "RAG"]}'
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"content": "RAGFlow 是一个开源的 RAG 引擎", "important_keywords": ["RAGFlow", "RAG"]}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks列出块
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 可选 | 页码 |
| page_size | integer | 可选 | 每页数量 |
cURL
curl -X GET "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789/chunks?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
DELETE/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks删除块
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| chunk_ids | array | 必填 | 要删除的块 ID 列表 |
cURL
curl -X DELETE "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789/chunks" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"chunk_ids": ["chunk-aaa111"]}'
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"chunk_ids": ["chunk-aaa111"]}
response = requests.delete(url, json=payload, headers=headers)
print(response.json())
PUT/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}更新块
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| content | string | 可选 | 更新块内容 |
| important_keywords | array | 可选 | 更新关键词 |
| question | string | 可选 | 更新关联问题 |
| available | integer | 可选 | 是否启用：0 禁用，1 启用 |
cURL
curl -X PUT "http://localhost:80/api/v1/datasets/ds-abc123/documents/doc-xyz789/chunks/chunk-aaa111" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"content": "更新后的块内容", "important_keywords": ["RAGFlow", "GraphRAG"]}'
Python
import requests
dataset_id = "ds-abc123"
document_id = "doc-xyz789"
chunk_id = "chunk-aaa111"
url = f"http://localhost:80/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"content": "更新后的块内容", "important_keywords": ["RAGFlow", "GraphRAG"]}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
检索服务
支持向量检索与知识图谱混合检索，是 GraphRAG 的核心查询能力
混合检索：当数据集配置了 GraphRAG 时，检索 API 会同时利用向量相似度和图谱关系进行混合检索，通过
vector_similarity_weight 参数控制向量与图谱的权重比例。POST/api/v1/retrieval检索相关块支持向量图谱混合检索
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| question | string | 必填 | 检索问题 |
| dataset_ids | array | 必填 | 数据集 ID 列表 |
| document_ids | array | 可选 | 限定文档 ID 列表 |
| page | integer | 可选 | 页码，默认 1 |
| page_size | integer | 可选 | 每页数量，默认 30 |
| similarity_threshold | float | 可选 | 相似度阈值，默认 0.2 |
| vector_similarity_weight | float | 可选 | 向量相似度权重 (0~1)，图谱权重=1-此值 |
| top_k | integer | 可选 | 返回 Top K 结果，默认 1024 |
| rerank_id | string | 可选 | Rerank 模型 ID |
| keyword | boolean | 可选 | 是否启用关键词检索 |
| highlight | boolean | 可选 | 是否高亮匹配内容 |
响应示例
JSON Response
{
"code": 0,
"data": {
"chunks": [
{
"chunk_id": "chunk-aaa111",
"content": "RAGFlow 支持知识图谱构建...",
"similarity": 0.85,
"document_id": "doc-xyz789",
"dataset_id": "ds-abc123"
}
],
"total": 15
}
}
cURL
curl -X POST "http://localhost:80/api/v1/retrieval" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"question": "RAGFlow 如何构建知识图谱？", "dataset_ids": ["ds-abc123"], "page": 1, "page_size": 10, "similarity_threshold": 0.2, "vector_similarity_weight": 0.7, "top_k": 1024, "keyword": false, "highlight": true}'
Python
import requests
url = "http://localhost:80/api/v1/retrieval"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {
"question": "RAGFlow 如何构建知识图谱？",
"dataset_ids": ["ds-abc123"],
"page": 1, "page_size": 10,
"similarity_threshold": 0.2,
"vector_similarity_weight": 0.7,
"top_k": 1024,
"keyword": False,
"highlight": True
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
聊天助手
创建和管理聊天助手，关联知识图谱数据集以实现基于图谱的智能问答
POST/api/v1/chats创建聊天助手
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 必填 | 助手名称 |
| dataset_ids | array | 必填 | 关联数据集 ID 列表 |
| llm | object | 可选 | LLM 配置 |
| prompt | object | 可选 | 提示词配置 |
响应示例
JSON Response
{
"code": 0,
"data": {
"id": "chat-abc123",
"name": "KG Assistant",
"dataset_ids": [
"ds-abc123"
]
}
}
cURL
curl -X POST "http://localhost:80/api/v1/chats" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "KG Assistant", "dataset_ids": ["ds-abc123"]}'
Python
import requests
url = "http://localhost:80/api/v1/chats"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "KG Assistant", "dataset_ids": ["ds-abc123"]}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/chats列出聊天助手
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 可选 | 页码 |
| page_size | integer | 可选 | 每页数量 |
| name | string | 可选 | 按名称过滤 |
cURL
curl -X GET "http://localhost:80/api/v1/chats?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
url = "http://localhost:80/api/v1/chats"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
PUT/api/v1/chats/{chat_id}更新聊天助手
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 可选 | 助手名称 |
| dataset_ids | array | 可选 | 关联数据集 |
| llm | object | 可选 | LLM 配置 |
| prompt | object | 可选 | 提示词配置 |
cURL
curl -X PUT "http://localhost:80/api/v1/chats/chat-abc123" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "Updated KG Assistant"}'
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "Updated KG Assistant"}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
DELETE/api/v1/chats/{chat_id}删除聊天助手
cURL
curl -X DELETE "http://localhost:80/api/v1/chats/chat-abc123" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
response = requests.delete(url, headers=headers)
print(response.json())
会话管理
管理聊天助手内的会话，每个会话维护独立的对话上下文
POST/api/v1/chats/{chat_id}/sessions创建会话
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 可选 | 会话名称 |
cURL
curl -X POST "http://localhost:80/api/v1/chats/chat-abc123/sessions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "New Session"}'
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}/sessions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "New Session"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/chats/{chat_id}/sessions列出会话
cURL
curl -X GET "http://localhost:80/api/v1/chats/chat-abc123/sessions?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}/sessions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
PUT/api/v1/chats/{chat_id}/sessions/{session_id}更新会话
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 可选 | 会话名称 |
cURL
curl -X PUT "http://localhost:80/api/v1/chats/chat-abc123/sessions/sess-xyz789" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Session"}'
Python
import requests
chat_id = "chat-abc123"
session_id = "sess-xyz789"
url = f"http://localhost:80/api/v1/chats/{chat_id}/sessions/{session_id}"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"name": "Updated Session"}
response = requests.put(url, json=payload, headers=headers)
print(response.json())
DELETE/api/v1/chats/{chat_id}/sessions删除会话
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ids | array | 必填 | 要删除的会话 ID 列表 |
cURL
curl -X DELETE "http://localhost:80/api/v1/chats/chat-abc123/sessions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"ids": ["sess-xyz789"]}'
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}/sessions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"ids": ["sess-xyz789"]}
response = requests.delete(url, json=payload, headers=headers)
print(response.json())
对话接口
与聊天助手进行实时对话，支持流式和非流式响应，可结合知识图谱进行回答
POST/api/v1/chats/{chat_id}/completions与聊天助手对话
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| question | string | 必填 | 用户问题 |
| session_id | string | 可选 | 会话 ID（不传则创建新会话） |
| stream | boolean | 可选 | 是否流式输出，默认 true |
| dataset_ids | array | 可选 | 指定检索的数据集 |
响应示例
JSON Response
{
"code": 0,
"data": {
"answer": "RAGFlow 通过 GraphRAG 模块构建知识图谱...",
"reference": {
"chunks": [
{
"chunk_id": "chunk-aaa111",
"similarity": 0.85
}
]
}
}
}
cURL
curl -X POST "http://localhost:80/api/v1/chats/chat-abc123/completions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"question": "RAGFlow 如何构建知识图谱？", "stream": false}'
Python
import requests
chat_id = "chat-abc123"
url = f"http://localhost:80/api/v1/chats/{chat_id}/completions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"question": "RAGFlow 如何构建知识图谱？", "stream": False}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
POST/api/v1/chats_openai/{chat_id}/chat/completionsOpenAI兼容对话接口
OpenAI 兼容：此接口兼容 OpenAI Chat Completions API 格式，可直接替换 OpenAI 的 base_url 使用。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| messages | array | 必填 | 消息列表，格式同 OpenAI |
| stream | boolean | 可选 | 是否流式输出 |
| session_id | string | 可选 | 会话 ID |
cURL
curl -X POST "http://localhost:80/api/v1/chats_openai/chat-abc123/chat/completions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "RAGFlow 如何构建知识图谱？"}], "stream": false}'
Python
from openai import OpenAI
client = OpenAI(
api_key="ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm",
base_url="http://localhost:80/api/v1/chats_openai/chat-abc123"
)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "RAGFlow 如何构建知识图谱？"}],
stream=False
)
print(response.choices[0].message.content)
代理管理
管理 RAGFlow 代理（Agent），代理可编排复杂工作流并调用知识图谱
POST/api/v1/agents/{agent_id}/sessions与代理创建会话
cURL
curl -X POST "http://localhost:80/api/v1/agents/agent-abc123/sessions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json"
Python
import requests
agent_id = "agent-abc123"
url = f"http://localhost:80/api/v1/agents/{agent_id}/sessions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
response = requests.post(url, headers=headers)
print(response.json())
POST/api/v1/agents/{agent_id}/completions与代理对话
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| question | string | 必填 | 用户问题 |
| session_id | string | 可选 | 会话 ID |
| stream | boolean | 可选 | 是否流式输出 |
cURL
curl -X POST "http://localhost:80/api/v1/agents/agent-abc123/completions" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"question": "帮我分析知识图谱中的实体关系", "stream": false}'
Python
import requests
agent_id = "agent-abc123"
url = f"http://localhost:80/api/v1/agents/{agent_id}/completions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm", "Content-Type": "application/json"}
payload = {"question": "帮我分析知识图谱中的实体关系", "stream": False}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
GET/api/v1/agents/{agent_id}/sessions列出代理会话
cURL
curl -X GET "http://localhost:80/api/v1/agents/agent-abc123/sessions?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
agent_id = "agent-abc123"
url = f"http://localhost:80/api/v1/agents/{agent_id}/sessions"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
GET/api/v1/agents列出代理
cURL
curl -X GET "http://localhost:80/api/v1/agents?page=1&page_size=30" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
Python
import requests
url = "http://localhost:80/api/v1/agents"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
params = {"page": 1, "page_size": 30}
response = requests.get(url, headers=headers, params=params)
print(response.json())
知识图谱专项 (GraphRAG)
RAGFlow GraphRAG 的完整配置说明与构建工作流
GraphRAG 是 RAGFlow 的知识图谱增强检索模块。通过在数据集级别配置 GraphRAG 参数，系统在解析文档时会自动抽取实体和关系，构建知识图谱，并在检索时结合图谱关系进行混合检索，显著提升复杂查询的准确度。
GraphRAG 配置参数详解
chunk_method
设为 "graphrag" 以启用知识图谱构建模式
string: "graphrag"
graphrag.entity_types
定义要从文档中抽取的实体类型列表
array<string>
graphrag.method
图谱构建方法：light（轻量快速）或 general（通用高精度）
string: "light" | "general"
graphrag.community
是否启用社区检测，发现图谱中的实体群落
boolean, 默认 false
graphrag.resolution
是否启用实体消解，合并指向同一实体的不同表述
boolean, 默认 false
实体类型配置
通过 graphrag.entity_types 定义要从文档中抽取的实体类别：
Organization
组织机构，如公司、政府部门、非营利组织
Person
人物，如企业高管、研究人员、公众人物
Geo
地理位置，如城市、国家、地区
Event
事件，如会议、产品发布、历史事件
Category
分类/概念，如技术领域、产品类别
构建方法选择
light
轻量模式：速度快，资源消耗低，适合大规模文档的快速图谱构建。使用简化抽取策略。
general
通用模式：精度高，实体和关系抽取更完整，适合对图谱质量要求较高的场景。
图谱构建工作流
1
创建数据集
配置 chunk_method=graphrag 及 graphrag 参数
2
上传文档
将文档上传至 GraphRAG 数据集
3
触发解析
调用 parse API 启动图谱构建
4
图谱检索
使用 retrieval API 进行混合检索
5
智能问答
通过 chat API 获取基于图谱的回答
完整 GraphRAG 工作流代码示例
cURL - 完整工作流
# 步骤1: 创建 GraphRAG 数据集
curl -X POST "http://localhost:80/api/v1/datasets" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"name": "kg-dataset", "chunk_method": "graphrag", "graphrag": {"entity_types": ["Organization", "Person", "Geo", "Event", "Category"], "method": "light", "community": true, "resolution": true}}'
# 步骤2: 上传文档
curl -X POST "http://localhost:80/api/v1/datasets/{dataset_id}/documents" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-F "file=@knowledge_base.pdf"
# 步骤3: 触发解析（构建图谱）
curl -X POST "http://localhost:80/api/v1/datasets/{dataset_id}/documents/{doc_id}/parse" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"
# 步骤4: 混合检索
curl -X POST "http://localhost:80/api/v1/retrieval" \
-H "Authorization: Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm" \
-H "Content-Type: application/json" \
-d '{"question": "相关组织之间有什么合作关系？", "dataset_ids": ["{dataset_id}"], "vector_similarity_weight": 0.5}'
Python - 完整工作流
import requests
BASE = "http://localhost:80"
headers = {"Authorization": "Bearer ragflow-IzMDY0MzE5YWUxMWEyM2FiOTM0NTI0Mm"}
# 步骤1: 创建 GraphRAG 数据集
resp = requests.post(f"{BASE}/api/v1/datasets", json={
"name": "kg-dataset",
"chunk_method": "graphrag",
"graphrag": {
"entity_types": ["Organization", "Person", "Geo", "Event", "Category"],
"method": "light",
"community": True,
"resolution": True
}
}, headers={**headers, "Content-Type": "application/json"})
dataset_id = resp.json()["data"]["id"]
print(f"数据集已创建: {dataset_id}")
# 步骤2: 上传文档
with open("knowledge_base.pdf", "rb") as f:
resp = requests.post(
f"{BASE}/api/v1/datasets/{dataset_id}/documents",
headers=headers, files={"file": f}
)
doc_id = resp.json()["data"][0]["id"]
print(f"文档已上传: {doc_id}")
# 步骤3: 触发解析（构建图谱）
resp = requests.post(
f"{BASE}/api/v1/datasets/{dataset_id}/documents/{doc_id}/parse",
headers=headers
)
print("解析已触发，图谱构建中...")
# 步骤4: 混合检索
resp = requests.post(f"{BASE}/api/v1/retrieval", json={
"question": "相关组织之间有什么合作关系？",
"dataset_ids": [dataset_id],
"vector_similarity_weight": 0.5
}, headers={**headers, "Content-Type": "application/json"})
print("检索结果:", resp.json())
RAGFlow 知识图谱 API 参考手册 | 基于 RAGFlow 官方 API 文档整理