输入格式
GraphRAG支持多种输入格式以简化数据导入过程。本文将讨论输入文件加载机制和文本分块功能。
输入加载与数据结构
所有输入格式在GraphRAG中加载后，都会转换为documents DataFrame传递给索引流水线。该DataFrame为每个文档创建一行记录，使用统一的列结构：
| 名称 | 类型 | 描述 |
|---|---|---|
| id | str | 文档ID。通过对文本内容进行哈希计算生成，确保多次运行结果一致。 |
| text | str | 文档完整文本内容。 |
| title | str | 文档名称。部分格式允许自定义此字段。 |
| creation_date | str | 文档创建日期，以ISO8601格式字符串表示。从源文件系统获取。 |
| metadata | dict | 可选文档元数据字典。详见下文说明。 |
索引流水线完成后保存到parquet文件的最终文档表结构，请参考输出文档说明。
支持格式
我们默认支持三种文件格式，覆盖绝大多数使用场景。如需其他格式，建议编写脚本转换为以下通用格式：
纯文本
.txt后缀的纯文本文件。整个文件内容作为text字段导入，title固定使用文件名。
CSV格式
.csv后缀的逗号分隔文件。使用pandas的read_csv方法加载，默认配置下每行视为独立文档。多文件会自动合并为统一DataFrame。
可通过settings.yaml的input模块配置：
- text_column：指定文本内容列（默认"text"）
- title_column：指定标题列（未配置则使用文件名）
- 若存在"id"列则直接使用，否则自动生成
JSON格式
.json后缀的结构化文件。使用Python的json.loads方法解析，支持：
- 单个JSON对象文件
- 根节点为对象数组的文件
（注：暂不支持jsonl格式）
配置方式与CSV相同，text_column和title_column对应JSON对象属性名。
元数据处理
对于结构化文件(CSV/JSON)，可通过配置将指定列保存为metadata字典字段。该元数据可在后续GraphRAG流水线中调用。
示例
software.csv
text,title,tag
My first program,Hello World,tutorial
An early space shooter game,Space Invaders,arcade
settings.yaml
文档DataFrame
| id | 标题 | 文本内容 | 创建日期 | 元数据 |
|---|---|---|---|---|
| (根据文本生成) | Hello World | My first program | (software.csv创建日期) | { "title": "Hello World", "tag": "tutorial" } |
| (根据文本生成) | Space Invaders | An early space shooter game | (software.csv创建日期) | { "title": "Space Invaders", "tag": "arcade" } |
分块与元数据
如默认数据流所述，文档会被分块为更小的"文本单元"进行处理。这是因为文档内容常超出语言模型的上下文窗口限制。分块参数中最重要的两个配置是chunk_size和overlap。我们还支持元数据处理方案来优化特定场景的索引效果。
典型场景示例：索引新闻文章集时，每篇文章开头包含标题和作者信息。默认分块会按配置的块大小均匀分割，导致开头信息仅出现在第一块中。当后续检索这些分块时，模型可能缺失应持续提供的文档来源信息。我们提供配置选项可将元数据复制到每个文本单元。
输入配置
导入文档时可指定metadata列列表，这是实现分块级元数据复制的前提条件。
分块配置
chunks模块需配置元数据处理方式：
- prepend_metadata：将每行的metadata字典内容以键值对形式添加到所有文本块开头
- chunk_size_includes_metadata：控制块大小计算方式
- False(默认)：先按chunk_size分块，再添加元数据（最终块可能超过设定大小）
- True：从设定块大小中扣除元数据长度（确保最终块严格符合设定大小）
文本文件示例
使用两个独立新闻文本文件演示分块效果（注：本例用单词数模拟token计数，实际语言模型token与单词并不等同）。
--
文件: US to lift most federal COVID-19 vaccine mandates.txt
内容: 华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着拜登政府开始将COVID-19视为常规地方性疾病。"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。
--
文件: NY lawmakers begin debating budget 1 month after due date.txt
内容: 奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含"对纽约人的重大胜利"。"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用"限制最小"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。
--
settings.yaml
input:
file_type: text
metadata: [title]
chunks:
size: 100
overlap: 0
prepend_metadata: true
chunk_size_includes_metadata: false
文档DataFrame
| id | 标题 | 文本内容 | 创建日期 | 元数据 |
|---|---|---|---|---|
| (根据文本生成) | US to lift most federal COVID-19 vaccine mandates.txt | (文件完整内容) | (文章txt创建日期) | { "title": "US to lift most federal COVID-19 vaccine mandates.txt" } |
| (根据文本生成) | NY lawmakers begin debating budget 1 month after due date.txt | (文件完整内容) | (文章txt创建日期) | { "title": "NY lawmakers begin debating budget 1 month after due date.txt" } |
原始文本块
| 内容 | 长度 |
|---|---|
| title: US to lift most federal COVID-19 vaccine mandates.txt 华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着拜登政府开始将COVID-19视为 |
109 |
| title: US to lift most federal COVID-19 vaccine mandates.txt 常规地方性疾病。"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。 |
82 |
| title: NY lawmakers begin debating budget 1 month after due date.txt 奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含"对纽约人的重大胜利"。"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用"限制最小"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。 |
111 |
此例展示两个输入文档被解析为五个文本块。文件名作为标题被添加但不计入块长度，每个文档的最后文本块通常小于设定块大小。
CSV文件示例
使用单个CSV文件存储两篇新闻（注：示例中文本内容未做CSV格式转义处理）。
--
文件: articles.csv
内容
headline,article
US to lift most federal COVID-19 vaccine mandates,华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着拜登政府开始将COVID-19视为常规地方性疾病。"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。
NY lawmakers begin debating budget 1 month after due date,奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含"对纽约人的重大胜利"。"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用"限制最小"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。
--
settings.yaml
input:
file_type: csv
title_column: headline
text_column: article
metadata: [headline]
chunks:
size: 50
overlap: 5
prepend_metadata: true
chunk_size_includes_metadata: true
文档DataFrame
| id | 标题 | 文本内容 | 创建日期 | 元数据 |
|---|---|---|---|---|
| (根据文本生成) | US to lift most federal COVID-19 vaccine mandates | (article列内容) | (articles.csv创建日期) | { "headline": "US to lift most federal COVID-19 vaccine mandates" } |
| (根据文本生成) | NY lawmakers begin debating budget 1 month after due date | (article列内容) | (articles.csv创建日期) | { "headline": "NY lawmakers begin debating budget 1 month after due date" } |
原始文本块
| 内容 | 长度 |
|---|---|
| title: US to lift most federal COVID-19 vaccine mandates 华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及 |
50 |
| title: US to lift most federal COVID-19 vaccine mandates 承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着 |
50 |
| title: US to lift most federal COVID-19 vaccine mandates 标志着拜登政府开始将COVID-19视为常规地方性疾病。"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。 |
38 |
| title: NY lawmakers begin debating budget 1 month after due date 奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含"对纽约人的重大胜利"。"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用"限制最小"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。 |
50 |
此例中两个输入文档被分割为十四个文本块。标题(headline)被添加且计入块长度计算，因此每个块严格符合设定大小（除最后一块）。配置的5个token重叠确保边界概念完整性。
为何需要重叠分块？当按token分割文档时，句子或关联概念常被截断。由于每个文本块被语言模型独立处理，重叠设计能确保这些截断概念至少在一个完整块中出现。
JSON文件示例
使用两个独立JSON文件存储新闻（字段内容与前述示例相同）。
--
文件: article1.json
内容
{
"headline": "US to lift most federal COVID-19 vaccine mandates",
"content": "华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着拜登政府开始将COVID-19视为常规地方性疾病。\"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，\"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。"
}
文件: article2.json
内容
{
"headline": "NY lawmakers begin debating budget 1 month after due date",
"content": "奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含\"对纽约人的重大胜利\"。\"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，\"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用\"限制最小\"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。"
}
--
settings.yaml
文档DataFrame
| id | 标题 | 文本内容 | 创建日期 | 元数据 |
|---|---|---|---|---|
| (根据文本生成) | US to lift most federal COVID-19 vaccine mandates | (content字段内容) | (article1.json创建日期) | { } |
| (根据文本生成) | NY lawmakers begin debating budget 1 month after due date | (content字段内容) | (article2.json创建日期) | { } |
原始文本块
| 内容 | 长度 |
|---|---|
| 华盛顿（美联社）白宫周一表示，拜登政府将在下周国家新冠公共卫生紧急状态结束时，取消最后剩余的大部分联邦COVID-19疫苗强制令。针对联邦雇员、承包商以及入境美国航空旅客的疫苗要求将于5月11日终止。政府同时开始取消对早教工作者、医护人员和美国陆地边境非公民的接种要求。这些强制令是联邦政府为推动疫苗接种采取的最后强制性措施，其终止标志着拜登政府开始将COVID-19视为 | 100 |
| 常规地方性疾病。"虽然这些疫苗令产生了巨大效益，但现在正是取消这些要求的合适时机，"白宫COVID-19协调员阿什什·杰哈博士周一告诉美联社。 | 83 |
| 奥尔巴尼（美联社）纽约州议员周一开始对逾期一个月的2290亿美元州预算进行表决，该预算将提高最低工资、打击非法大麻店并禁止新建筑使用燃气灶和供暖系统。由于对保释法修改等政策条款存在分歧，州长凯西·霍楚与民主党控制的立法机构协商超过4月1日的预算截止期。部分预算议案周一进入辩论阶段。州参议院多数党领袖安德烈娅·斯图尔特-考辛斯预计周二完成表决，称该预算包含"对纽约人的重大胜利"。"我们本希望更早完成，预算包含大量政策条款需要仔细斟酌，"考辛斯在表决前告诉记者。霍楚成功推动保释法修改，取消法官须采用"限制最小"手段确保被告到庭的标准。霍楚称法官需要更大裁量权，部分自由派议员认为这会削弱2019年通过的保释改革，导致更多低收入和有色人种被审前拘留。根据州官员说明，预算还包括：到2026年纽约市及郊区最低工资升至17美元，州其他地区16美元（现行标准分别为15美元和14.2美元）。 | 100 |
此例中两个JSON文档被解析为五个文本块。未添加元数据前缀，每个块严格符合设定大小（除最后一块）。配置的10个token重叠确保关键信息完整性。