社区数据通用使用说明

下载、API 和账号设置在哪里？

在“历史数据交付”中查看任务，并从已完成或部分完成的任务进入交付下载页面。API 密钥与接口文档统一放在“API”；额度、邮箱和通知设置位于“个人中心”。

可以获取哪些数据？

本说明适用于按社区及时间范围交付的公开帖子、评论和评论回复数据。具体社区名称、起止时间、记录数量、文件大小和文件校验值，应以对应订单的下载页面或交付清单为准。

交付数据为采集时能够获得的公开历史记录，不应被理解为平台官方数据副本，也不保证覆盖曾经存在但已删除、未归档或无法访问的全部内容。

下载包里包含哪些文件？

完整任务按帖子和评论分别提供合并文件；额度不足或部分分片失败时，可能暂时提供已完成的月度分片，补充额度或重试后再生成合并文件。常见结构如下：

delivery/ ├── posts.ndjson.gz 帖子合并文件 ├── comments.ndjson.gz 评论合并文件 ├── posts-2021-01.ndjson.gz 未完整任务的帖子分片 ├── comments-2021-01.ndjson.gz 未完整任务的评论分片 ├── manifest.json 数量、文件大小及校验值 └── README / 下载页面使用说明

manifest.json包含社区、时间范围、帖子数、评论数、交付方式、文件大小、生成时间和SHA-256校验值。合并只改变下载文件组织方式，不会改变记录内容或重复计费。

如何打开 NDJSON 和 GZ 文件？

默认交付格式为NDJSON + gzip。gzip用于压缩；NDJSON表示每一行均为一个独立JSON对象，而不是由方括号包裹的JSON数组。

{"id":"abc123","title":"First post","selftext":"Post body"}
{"id":"def456","title":"Second post","selftext":"Another body"}

NDJSON可以流式读取，适合从数万条到上亿条的不同规模。处理大型文件时，不应一次性将全部记录载入内存。

请勿使用普通的json.load()直接读取整个NDJSON文件。应逐行读取，并对每一行调用json.loads()。

怎样核对总条数和文件完整性？

下载后应使用交付清单中的SHA-256值校验文件。校验一致，表示文件在下载过程中未发生损坏或截断。

Windows PowerShell

Get-FileHash .\posts.ndjson.gz -Algorithm SHA256
Get-FileHash .\comments.ndjson.gz -Algorithm SHA256

Linux / macOS

sha256sum posts.ndjson.gz comments.ndjson.gz

分片订单应逐个校验文件。若校验值不一致，应重新下载对应分片，无须重新下载全部数据。

帖子和评论包含哪些字段？

帖子常用字段

字段	说明
`id`	帖子原始ID。
`name`	完整对象ID，通常为`t3_帖子ID`。
`subreddit`	社区名称。
`title`	帖子标题。
`selftext`	文字帖正文；链接帖可能为空。
`author`	采集时记录的作者名称；已删除账号可能显示`[deleted]`。
`created_utc`	UTC Unix时间戳。
`score`、`ups`	归档时记录的互动数值，不保证等于当前值。
`num_comments`	归档时记录的评论数量。
`permalink`	站内相对链接。
`url`	帖子链接或外部资源链接。
`media`、`secure_media`	视频等媒体的结构化信息，可能为空。

评论常用字段

字段	说明
`id`	评论原始ID。
`name`	完整评论ID，通常为`t1_评论ID`。
`link_id`	所属帖子，通常为`t3_帖子ID`。
`parent_id`	直接回复的对象，可能为帖子`t3_`或评论`t1_`。
`body`	评论正文。
`author`	采集时记录的评论作者。
`created_utc`	UTC Unix时间戳。
`score`	归档时记录的评论得分。
`permalink`	评论相关链接；历史记录中的链接字段可能不完整。

实际记录可能包含更多原始字段。不同年代、不同对象类型和不同归档状态下，部分字段可能缺失或为null，使用程序时应采用容错读取方式。

如何关联帖子、评论和回复？

帖子和评论通常分文件保存，但可通过ID完整还原所属关系和评论树。

将评论的link_id去掉t3_前缀，即得到所属帖子的id。
parent_id以t3_开头时，该评论为直接回复帖子的一级评论。
parent_id以t1_开头时，去掉前缀后得到父评论的id。

帖子：id = abc123，name = t3_abc123 ├── 一级评论：id = cmt001，link_id = t3_abc123，parent_id = t3_abc123 │ └── 评论回复：id = cmt002，link_id = t3_abc123，parent_id = t1_cmt001 └── 一级评论：id = cmt003，link_id = t3_abc123，parent_id = t3_abc123

由于删除或归档缺失，个别评论可能无法找到父评论。此类记录仍可通过link_id归入对应帖子，并标记为“父节点缺失”。

如何用程序读取数据？

以下代码可直接读取压缩文件，无须预先解压：

import gzip
import json

def read_ndjson_gzip(filename):
    with gzip.open(filename, "rt", encoding="utf-8") as source:
        for line in source:
            line = line.strip()
            if line:
                yield json.loads(line)

for post in read_ndjson_gzip("posts.ndjson.gz"):
    print(post.get("id"), post.get("title"))

关联帖子与评论

posts = {
    post["id"]: post
    for post in read_ndjson_gzip("posts.ndjson.gz")
}

for comment in read_ndjson_gzip("comments.ndjson.gz"):
    post_id = (comment.get("link_id") or "").removeprefix("t3_")
    post = posts.get(post_id)
    if post:
        print(post["title"], comment.get("body"))

小型订单可将帖子索引保存在内存中；千万级订单应使用SQLite、PostgreSQL、DuckDB、Parquet或其他分析系统，避免构建超大内存字典。

转换UTC时间

from datetime import datetime, timezone

value = datetime.fromtimestamp(record["created_utc"], timezone.utc)
print(value.isoformat())

可以用 Excel 或 CSV 吗？

NDJSON可以转换为CSV。建议仅选择业务需要的字段，避免将大量嵌套媒体结构直接写入单元格。

import csv, gzip, json

fields = ["id", "link_id", "parent_id", "author", "body", "score", "created_utc"]

with gzip.open("comments.ndjson.gz", "rt", encoding="utf-8") as source, \
     open("comments.csv", "w", newline="", encoding="utf-8-sig") as target:
    writer = csv.DictWriter(target, fieldnames=fields)
    writer.writeheader()
    for line in source:
        record = json.loads(line)
        writer.writerow({field: record.get(field) for field in fields})

Excel单个工作表最多约104万行，单元格文本长度也有限。超过该规模时，应按年月拆分CSV，或优先使用Parquet、DuckDB及数据库工具。CSV适合查看和交换，不适合表达嵌套媒体结构及完整评论树。

如何把数据用于 AI 分析？

交付数据可用于主题分析、情感分析、内容分类、社区趋势研究、RAG检索、动态示例库及经审核的模型训练。用于“根据帖子生成评论”时，可将帖子标题和正文作为输入，将符合条件的评论作为输出。

建议的训练前处理

剔除空内容、[deleted]、[removed]、机器人广告和重复记录。
根据长度、得分、层级、语言及人工质量标准筛选评论。
删除邮箱、电话、地址、账号等非必要个人信息。
按帖子ID划分训练集、验证集和测试集，防止同一讨论串跨集合泄漏。
保留原始ID用于内部去重，但不应将用户名作为模型学习目标。
高得分仅代表社区互动表现，不等同于事实正确或专业可靠。

{
  "instruction": "Write a relevant response to the community post.",
  "input": {"title": "...", "body": "..."},
  "output": "Selected and reviewed comment",
  "metadata": {"post_id": "...", "comment_id": "...", "score": 10}
}

健康、金融、法律等高风险社区可能包含错误、过时或具有误导性的建议。未经专业审核，不应将社区内容直接训练为面向用户的诊断、投资或法律结论。

是否包含图片和视频？

除非订单另有约定，数据文件通常只保存媒体URL、缩略图和结构化媒体字段，不包含图片或视频文件本身。可重点检查url、thumbnail、media和secure_media。

历史链接可能已经失效、跳转或改变内容。批量下载媒体会显著增加存储与流量成本，并可能受到第三方网站规则限制，因此不建议在未确认授权和需求的情况下自动下载全部媒体。

数据缺失、删除和重复如何理解？

score、ups和num_comments为归档时记录，不保证等于当前页面数值。
帖子的num_comments可能与实际交付评论数不同，原因包括删除、不可访问、归档缺失和统计口径差异。
作者为[deleted]并不必然表示正文同时被删除。
部分记录可能缺少可选字段；程序应使用record.get("field")等容错方式读取。
历史链接和媒体资源可能失效。
大型分片订单应以所有分片记录数之和为交付总量，并使用清单校验，避免重复导入。

邮件通知

平台会通过邮件发送账号注册验证、密码重置、任务完成、真正需要处理的任务失败和额度预警。请确保账号邮箱可正常收信，并将 RedditDate 发信地址加入可信发件人。

公开 API 文档只展示数据读取、历史归档、采集和导出接口；注册、邮箱验证、密码重置和评论助手等操作请在网页控制台完成。

部分分片失败但最终已有可下载文件的任务，会按完成任务处理，不会发送失败通知。临时数据读取波动、无新数据或系统已自动处理的问题也不会作为客户失败邮件发送。

邮件中的操作链接应只在本人发起注册、登录或密码修改时点击。如收到非本人操作邮件，请及时联系管理员处理。

如何按 Reddit 用户名读取帖子和评论？

使用 GET /v1/users/{username}/posts 和 GET /v1/users/{username}/comments 按发布时间倒序读取公开内容，返回记录计入普通数据额度。

如何按用户名读取指定日期范围的历史数据？

使用 GET /v1/bulk-history/users/{username}/posts 读取历史帖子，使用 GET /v1/bulk-history/users/{username}/comments 读取历史评论；必须提供 UTC 日期参数 date_from 和 date_to。

两个接口计入大额历史额度。每页最多 100 条，继续读取时把上一页的 next_cursor 作为 after_cursor。

数据使用有哪些注意事项？

数据使用方应根据其所在地区、应用场景和数据处理目的，自行评估适用的服务条款、著作权、隐私、个人信息保护及行业监管要求。

不得利用数据骚扰、跟踪、歧视或识别特定自然人。
不建议公开再发布包含用户名和敏感自述的完整数据副本。
用于模型训练或公开研究前，应进行去标识化、敏感信息清理和必要的风险评估。
下载链接及文件应仅提供给获得授权的人员，并在项目结束后按约定删除。
对删除请求、内容权利主张和安全事件，应建立相应的响应与处置流程。

本说明提供技术使用指引，不构成法律、医学、金融或其他专业意见。

Q&A

Windows PowerShell

Linux / macOS

帖子常用字段

评论常用字段

关联帖子与评论

转换UTC时间

建议的训练前处理