API/paper-schemaBETA

paper-schema 论文结构、证据与引用图谱

面向当前主要覆盖的 100 万+ AI 领域会议论文，检索结构化论文信息、定位原文证据并构建可下钻的引用图谱。

使用 Paper Schema Skill用 9 个意图工具完成结构化阅读、证据核验、实体发现和小范围论文图谱构建。

概述

paper-schema 将论文预先解析为 Paper、Entity、Relation、Evidence 与 Citation 等结构信息，并保留到原文段落的精确定位。Agent 可以先读取紧凑、明确的结构对象，只在需要核验时补取少量原文上下文，避免反复加载长篇全文，从而节约 Token，并更高效地完成多步检索、论文比较和小范围图谱构建。

适用场景

· 围绕一个 AI 研究主题，从 100 万+ 会议论文中筛选种子论文并构建小范围论文图谱
· 让 Agent 直接读取论文中的问题、方法组件、实验设置、指标与结论等结构化 Entity 和 Relation
· 按需将公式、表格、结果与引用语义等 Evidence 精确回溯到原文段落，减少无关全文读取
· 在保留完整引用列表的同时，对已解析引用继续下钻到目标论文

不适用场景

· 全量书目筛选、作者和期刊统计仍使用 meta-search。
· 开放式全文语义召回仍使用 agentic-search。
· Citation Edge 只覆盖已解析引用，不能替代完整 citation 数量。

能力边界

· 仅覆盖已完成 Schema 抽取的论文，不能替代 meta-search 的全量书目覆盖。
· 所有子路径共享 paper-schema 配额，但每个操作仍有独立的参数与容量上限。
· 完整 citations 与 resolved citation graph 分层返回，未解析引用不会被图接口补造。

鉴权

全部 /paper-schema 子路径统一使用 Sciverse API Token。先在控制台创建 Token，再通过 Authorization: Bearer 请求头传入；不要把 Token 放在 URL、请求体、浏览器前端代码或日志中。

前往控制台创建 API Token

export SCIVERSE_API_TOKEN='YOUR_API_TOKEN'

curl -X POST https://api.sciverse.space/paper-schema/search \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: paper-schema-example-001" \
  -d '{"query":"large language model agent","filters":{"published_year_gte":2022},"size":5}'

· 401 表示 Token 缺失、格式错误、无效或账号已禁用；修复鉴权后再请求，不要自动重试。
· 403 表示 Token 有效但当前账号没有对应能力或字段权限；需要开通权限。
· 429 表示账号、paper-schema 资源或调用来源触发配额；按 Retry-After 或错误体中的 retry_after 等待。
· X-Request-ID 可由客户端传入，也会由网关生成并回传；排查问题时请保留该值。
· 18 个子操作共享同一个 paper-schema 鉴权与配额资源，不需要为不同子路径创建不同 Token。

请求示例

curl -X POST https://api.sciverse.space/paper-schema/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"large language model agent","filters":{"published_year_gte":2022},"size":5}'

# 从响应 items[].schema_id 选择一篇论文，然后设置：
export SCHEMA_ID='schema_xxx'

18 个详细操作

Capability

读取公共合同版本、能力、Entity/Relation/Evidence 类型体系与调用限制。

GET/paper-schema

能力发现

返回当前公开合同版本、支持的 Entity、Relation 和 Evidence 类型，以及主要调用限制；用于能力发现，不作为健康检查。

概述

用于客户端启动时发现 Paper Schema 的合同版本、可用资源、公开 Entity/Relation/Evidence 分类和容量上限。它描述稳定能力，不用于判断服务或单篇论文是否可用。

适用场景

· 让 Skill 或 SDK 确认当前合同版本。
· 动态读取公开类型体系和批量上限。

不适用场景

· 不要用它监控服务状态或判断某篇论文是否存在。

请求参数

字段	类型	必填	说明
Authorization	header string	必填	Sciverse API Token，格式为 Bearer <token>。

请求示例

curl https://api.sciverse.space/paper-schema \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
contract_version	string	公共 API 合同版本。
resources	array<string>	可调用的公共资源。
entity_taxonomy / relation_taxonomy	object	公开类型与 subtype/关系类别。
evidence_groups	array<string>	Evidence 检索允许的高价值分组。
limits	object	分页、批量和图扩展上限。

参数边界

鉴权与计量: 计入 paper-schema 配额

说明

· 能力合同可以被客户端缓存；资源是否存在应调用对应查询接口判断。

Paper Discovery

通过元数据关键词、Entity 语义或已知论文的多信号关联发现论文；结果主体始终是论文。

POST/paper-schema/search

论文关键词与元数据搜索

在标题、摘要、作者、venue、主题、研究问题、贡献和 DOI 等公开字段中匹配关键词，并按年份等条件过滤。

概述

返回主体始终是论文。query 使用关键词相关性检索，覆盖标题、摘要、研究问题、核心贡献、主要结果、论文主旨、Topic、Task、作者和 Venue；它不是自然语言问答或全文向量语义搜索。Skill 或 LLM 收到长问题时，应先提取核心学术关键词再调用。

适用场景

· 按研究主题、方法名或任务名查找已完成 Schema 抽取的论文。
· 按 DOI 精确定位论文，或叠加年份、作者、Venue、代码和数据条件。
· 取得 schema_id 后继续查询 Entity、内部 Relation、Evidence 或外部 Citation。

不适用场景

· 搜索 Dataset、Problem 等结构对象，请使用 entities/search。
· 开放式全文语义召回，请使用 agentic-search。
· 全量书目筛选与导出，请使用 meta-search。

请求体（JSON）

字段	类型	必填	说明
query	string	可选	关键词查询；匹配论文标题、摘要及主要结构化语义字段。范围 1–500 字符
filters	object	可选	论文元数据过滤条件；query 与 filters 至少提供一项。默认 {}
sort	array<SortItem>	可选	按 year、metrics.citation_count、metrics.reference_count 或 metrics.fwci 排序；未传时，有 query 按相关性，无 query 按稳定主键顺序。范围最多 2 项
size	integer	可选	单页返回论文数。默认 20范围 1–100
cursor	string	可选	服务返回的深翻页令牌；调用方不得解析或自行构造。

filters 可用字段

字段	类型	值	说明
schema_ids	array<string>	最多 100 个	精确限定 Paper Schema 论文主键。
dois	array<string>	最多 100 个	按标准 DOI 精确查找，服务统一处理大小写。
authors	array<string>	最多 20 个	按作者规范化名称过滤。
venues	array<string>	最多 50 个	按 Venue 规范化名称过滤。
published_year_gte / published_year_lte	integer	1800–2200	限制发表年份范围。
has_code	boolean	true / false	是否存在代码资源信号。
has_data	boolean	true / false	是否存在数据资源信号。
is_oa	boolean	true / false	是否为开放获取论文。

请求示例

{
  "query": "large language model agent",
  "filters": {
    "published_year_gte": 2022,
    "has_code": true
  },
  "size": 20
}

响应结构

字段	类型	说明
total	object	命中论文总量及统计关系；大范围查询可能使用有界 total。
items	array<object>	论文卡片列表，结果单位始终为论文。
items[].schema_id	string	Paper Schema 的公共论文主键，用于后续结构资源下钻。
items[].title / abstract	string	论文标题和摘要。
items[].authors / venue / year	array / string / integer	作者、发表载体和年份。
items[].topics / tasks	array	论文主题和研究任务。
items[].research_problem	string	抽取并归一后的研究问题。
items[].central_contribution	string	论文核心贡献。
items[].headline_result	string	论文主要结果。
items[].has_code / has_data	boolean	代码和数据资源信号。
next_cursor	string \| null	下一页游标；为空表示没有下一页。

响应示例

{
  "contract_version": "2026-07-15",
  "total": {"value": 138, "relation": "eq"},
  "items": [
    {
      "schema_id": "schema_xxx",
      "title": "Large Language Model Agents",
      "abstract": "...",
      "authors": ["Example Author"],
      "venue": "Example Conference",
      "year": 2024,
      "topics": ["Large Language Models"],
      "research_problem": "How to build reliable autonomous research agents",
      "central_contribution": "A structured agent framework",
      "headline_result": "Improved task completion",
      "has_code": true,
      "has_data": false
    }
  ],
  "next_cursor": "opaque-cursor"
}

API 选择

按关键词、DOI、作者或年份找论文	`/paper-schema/search`
搜索 Dataset、Problem 等结构对象	`/paper-schema/entities/search`
从一个 Entity 名称展开相关论文	`/paper-schema/entities/related-papers`
从一篇已知论文综合发现相关论文	`/paper-schema/schemas/{schema_id}/related-papers`
在单篇论文正文中查内容	`/paper-schema/search-in-schema`

参数边界

query 长度: 1–500 字符
单页论文数: 1–100
schema_ids / dois: 各最多 100 个
sort: 最多 2 项

说明

· 精确 DOI 查询放入 filters.dois，不要把整句“文章 DOI 是……”作为 query。
· 同一 Dataset 或方法的跨论文对象展开属于 Entity 语义搜索，不属于本接口。

POST/paper-schema/entities/related-papers

从 Entity 语义展开论文

按 Entity 名称、type、subtype 和描述模糊匹配其他论文；不把跨论文 Entity 视为已完成身份对齐。

概述

把 Dataset、Problem、Method、Component 等对象名称作为语义线索，跨论文检索相似 Entity，再按 schema_id 聚合成论文候选。由于当前 Entity 是逐篇独立抽取，匹配表示名称/描述相似，不代表全局对象身份已对齐。

适用场景

· 从某篇论文里的 Dataset 名称继续找使用同类数据的论文。
· 按研究问题或方法组件扩展相关论文。

不适用场景

· 已知论文的综合相关性请使用 schemas/{schema_id}/related-papers。
· 需要 Entity 本身而非论文时使用 entities/search。

请求参数

字段	类型	必填	说明
query	string	必填	Entity 名称或简短描述。范围 1–500 字符
entity_types / entity_subtypes	array<string>	可选	限定公开 Entity 类型和 subtype。
exclude_schema_ids	array<string>	可选	排除种子论文或已展示论文。范围最多 100 个
size / cursor	integer / string	可选	分页大小与服务返回的游标。默认 20 / null

请求示例

{
  "query": "MMLU",
  "entity_types": ["Resource"],
  "entity_subtypes": ["Dataset"],
  "size": 20
}

响应结构

字段	类型	说明
items[].schema_id	string	候选论文主键。
items[].schema_paper	object	论文元数据卡片。
items[].matched_entities	array<object>	触发匹配的 Entity 摘要。
items[].match_reasons	array<string>	可解释匹配原因。
next_cursor	string \| null	下一页游标。

参数边界

单页论文: 1–100
匹配含义: 语义相似，不承诺实体同一性

说明

· 公共接口不接受跨论文 entity_id 精确匹配，因为 entity_id 只在当前论文语境内稳定。

POST/paper-schema/schemas/{schema_id}/related-papers

从已知论文发现相关论文

融合 Entity、关键词和 Citation 信号，为一篇已知论文生成可解释的相关论文候选。

概述

从路径中的种子 schema_id 读取论文主题、关键词和关键 Entity，并可叠加已解析 Citation Edge，生成去重后的相关论文候选。请求参数中的 term 表示关键词信号；每个结果都会说明各信号的贡献。

适用场景

· 阅读一篇论文后继续发现方法相近或问题相同的论文。
· 为主题图谱选择一跳扩展节点。

不适用场景

· 完整引用列表应使用 citations；本接口的 citation 只是相关性信号。

请求参数

字段	类型	必填	说明
schema_id	path string	必填	种子论文的公共 schema_id。
signals	array<term\|entity\|citation>	可选	参与候选生成的信号。默认三种全部范围 1–3 项
exclude_same_work	boolean	可选	排除同一作品的其他版本。默认 true
size	integer	可选	候选论文数量。默认 20范围 1–50

请求示例

{
  "signals": ["entity", "citation"],
  "exclude_same_work": true,
  "size": 20
}

响应结构

字段	类型	说明
seed	object	种子论文摘要。
items[].schema_id	string	相关论文主键。
items[].score_components	object	term、entity、citation 各信号的得分贡献。
items[].reasons	array<string>	可展示的相关原因。

参数边界

候选数: 1–50
Citation: 仅使用已解析论文边

说明

· 未解析的 Reference 不会参与 citation 相关性，但仍保留在完整 citations 接口中。

Entity

发现和读取论文中的结构对象。

POST/paper-schema/entities/search

Entity 搜索

返回匹配的 Problem、Component、Finding、Measure、Resource、Reference 等结构对象，而不是论文列表。

概述

跨论文搜索结构对象，返回结果单位是 Entity。适合查 Dataset、Problem、Finding、Measure、Resource 等对象及其所属论文；如需最终返回论文列表，应使用 entities/related-papers。

适用场景

· 查找名称包含 MMLU 的 Dataset/Resource。
· 在一组 schema_id 中定位 Problem 或实验指标。

不适用场景

· 它不是论文搜索，也不把相似 Entity 自动合并成全局唯一对象。

请求参数

字段	类型	必填	说明
query	string	可选	匹配 Entity 名称、标题、文本和描述；未限定 schema_ids 时必填。范围 1–500 字符
filters.schema_ids	array<string>	可选	限定论文范围。范围最多 100 个
filters.entity_types / entity_subtypes	array<string>	可选	限定公开类型和 subtype。
filters.sections	array<string>	可选	限定来源章节。范围最多 50 个
hydrate_schema_papers	boolean	可选	是否附带论文卡片。默认 false
size / cursor	integer / string	可选	分页参数。默认 20 / null范围 1–100

请求示例

{
  "query": "MMLU",
  "filters": {
    "entity_types": ["Resource"],
    "entity_subtypes": ["Dataset"]
  },
  "hydrate_schema_papers": true,
  "size": 20
}

响应结构

字段	类型	说明
items[].schema_id / entity_id	string	所属论文和论文内 Entity 主键。
items[].entity_type / entity_subtype	string	公开类型体系。
items[].name / text	string	对象名称和描述文本。
items[].provenance	array<object>	可用于原文回溯的定位信息。
items[].schema_paper	object \| null	按需附带的论文卡片。

参数边界

单页 Entity: 1–100
无 query: 必须限定 schema_ids

说明

· entity_id 用于当前论文内下钻，不应作为跨论文对象身份。

GET/paper-schema/schemas/{schema_id}/entities

单篇论文 Entity 列表

分页读取一篇论文的全部 Entity，或按 type、subtype、section 筛选。

概述

完整、可分页地读取一篇论文的 Entity 集合。它是获取“该论文里有哪些结构对象”的主入口，不像 Materials 那样按目标裁剪。

适用场景

· 加载论文结构图谱的全部节点。
· 只取 Problem、Resource/Dataset 或 Finding。

不适用场景

· 跨论文搜索请使用 entities/search；任务材料裁剪请使用 materials。

请求参数

字段	类型	必填	说明
schema_id	path string	必填	论文主键。
entity_types / entity_subtypes	query array<string>	可选	按类型或 subtype 筛选。
sections	query array<string>	可选	按来源章节筛选。
size / cursor	query integer / string	可选	分页参数。默认 50 / null范围 1–100

请求示例

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/entities?entity_types=Resource&entity_subtypes=Dataset&size=50" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
schema_id	string	当前论文。
total	object	筛选后的 Entity 总量。
items	array<Entity>	Entity 完整列表页。
next_cursor	string \| null	下一页游标。

参数边界

单页: 1–100

说明

· 需要全量时持续使用 next_cursor，不能把 Materials 的 returned 当作完整集合。

GET/paper-schema/schemas/{schema_id}/entities/{entity_id}

Entity 详情

读取当前论文中的一个具体节点，用于 Relation 端点、Evidence 和 provenance 下钻。

概述

精确读取某篇论文内的一个 Entity，并可选附带与它相连的内部 Relation。典型调用来自 Entity 列表、Relation 端点或 Evidence 的 source_entity_id。

适用场景

· 图谱界面点击节点后加载详情。
· 从 Evidence 或 Relation 回到源 Entity。

不适用场景

· 不要用 entity_id 在其他论文中寻找同一对象。

请求参数

字段	类型	必填	说明
schema_id / entity_id	path string	必填	论文与论文内 Entity 主键。
include_relations	query boolean	可选	是否附带相邻内部 Relation。默认 false
relation_limit	query integer	可选	附带关系上限。默认 50范围 1–100

请求示例

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/entities/ENTITY_ID?include_relations=true&relation_limit=20" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
entity	object	Entity 类型、名称、文本、章节和 provenance。
relations	array<object>	按需返回的相邻内部关系。
relations_truncated	boolean	是否达到关系上限。

参数边界

相邻关系: 最多 100 条

说明

· 不存在或不属于该 schema_id 的 entity_id 返回 404。

Internal Relations

只查询已知论文或 Entity 范围内的文档内部结构关系；论文间引用由 Citations 接口负责。

POST/paper-schema/relations/search

内部 Relation 查询

在指定 schema_id 或 Entity 范围内，按公开 relation type 查询文档内部关系。

概述

查询论文内部 Entity 之间的结构关系，例如 uses_component、evaluates、reports_metric、supports、resolves。调用必须限定论文、关系类型或端点 Entity，避免把内部关系误当成无边界全局图。

适用场景

· 查某篇论文的方法组件如何连接到 Problem 和 Finding。
· 从 Dataset/Measure 节点读取相邻实验关系。

不适用场景

· 论文之间的引用关系请使用 Citations 接口。

请求参数

字段	类型	必填	说明
filters.schema_ids	array<string>	可选	限定论文范围。范围最多 100 个
filters.source_entity_ids / target_entity_ids	array<string>	可选	限定关系端点。范围各最多 100 个
filters.relation_types	array<string>	可选	公开关系类别。范围最多 50 个
evidence_query	string	可选	对关系证据文本增加关键词约束。范围 1–500 字符
include_context	none\|entities	可选	是否附带两端 Entity 摘要。默认 none
size / cursor	integer / string	可选	分页参数。默认 20 / null范围 1–100

请求示例

{
  "filters": {
    "schema_ids": ["SCHEMA_ID"],
    "relation_types": ["evaluates", "reports_metric"]
  },
  "include_context": "entities",
  "size": 50
}

响应结构

字段	类型	说明
items[].relation_id	string	当前论文内关系主键。
items[].relation_type	string	公开逻辑关系类别。
items[].source_entity_id / target_entity_id	string	两端 Entity。
items[].source_entity / target_entity	object \| null	按需附带的端点摘要。
items[].provenance	array<object>	关系证据定位。

参数边界

单页关系: 1–100
结构约束: 至少提供一种结构筛选

说明

· 关系类别以能力发现接口返回的 relation_taxonomy 为准。

GET/paper-schema/schemas/{schema_id}/relations/{relation_id}

Relation 详情

读取一条逻辑 Relation、两端 Entity 摘要和合并后的 provenance。

概述

精确读取一条论文内部 Relation，默认补齐 source/target Entity 摘要和合并后的证据定位，适合图谱边点击和证据下钻。

适用场景

· 点击结构图中的边查看关系类型和两端对象。
· 把关系证据回溯到原文段落。

不适用场景

· 它不返回论文到论文的 Citation Edge。

请求参数

字段	类型	必填	说明
schema_id / relation_id	path string	必填	论文和论文内关系主键。
include_context	query boolean	可选	是否附带两端 Entity 和证据摘要。默认 true

请求示例

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/relations/RELATION_ID?include_context=true" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
relation	object	逻辑关系及公开字段。
source_entity / target_entity	object \| null	两端节点摘要。
provenance	array<object>	去重合并后的原文定位。

参数边界

作用域: 单篇论文内部

说明

· relation_id 必须与 schema_id 匹配，否则返回 404。

External Citations

Reference 是论文内部的参考文献节点，citations 返回完整引用列表；解析成功的 Reference 才形成论文间 Citation Edge，供 citation-graph 下钻。图边数量不等于完整引用数或外部被引次数。

GET/paper-schema/schemas/{schema_id}/citation-summary

引用概览

区分完整 Reference/Citation 总量、解析覆盖率和论文级入边/出边。

概述

一次返回当前论文的完整参考文献数量、引用 Relation 数、已解析/未解析 Reference 数，以及语料内论文级出边和入边。它用于先判断引用数据完整度，再决定是否下钻列表或图。

适用场景

· 论文详情页显示参考文献总数和解析覆盖率。
· 构图前判断是否存在可下钻的论文级边。

不适用场景

· 它只返回统计，不返回具体 Reference 或边。

请求参数

字段	类型	必填	说明
schema_id	path string	必填	当前论文主键。

请求示例

curl https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citation-summary \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
outbound.reference_count_total	integer	完整 Reference Entity 数。
outbound.resolved_reference_count / unresolved_reference_count	integer	已解析和未解析数量。
outbound.resolution_coverage	number	Reference 解析覆盖率。
outbound.resolved_target_schema_count	integer	可跳转的目标论文数。
inbound.external_citation_count	integer \| null	外部元数据中的总被引数。
inbound.resolved_corpus_edge_count	integer	当前语料内可解析入边数。

参数边界

查询: 单篇论文聚合

说明

· resolved 数低于 reference 总数属于解析覆盖差异，不代表完整引用数据丢失。

GET/paper-schema/schemas/{schema_id}/citations

完整外部引用列表

同时返回 resolved 与 unresolved 引用；目标论文尚未解析时，原始 Reference 仍会保留。

概述

按论文中的 citation Relation 分页返回完整 Reference 信息。每条原始引用都会保留；解析成功的项额外提供 target_schema_id 和目标论文卡片，未解析项明确标记 unresolved。

适用场景

· 展示论文完整参考文献列表。
· 对已解析引用显示“查看目标论文”入口，同时保留不能跳转的引用。

不适用场景

· 需要多跳论文图时使用 citation-graph。

请求参数

字段	类型	必填	说明
schema_id	path string	必填	当前论文主键。
size	query integer	可选	每页引用数。默认 50范围 1–100
cursor	query string	可选	下一页游标。

请求示例

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citations?size=50" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
total	integer	完整 citation Relation 总数。
items[].relation	object	原始引用关系。
items[].reference	object \| null	Reference Entity 的题名、作者、年份等。
items[].resolution.status	resolved\|unresolved\|target_unavailable	解析状态。
items[].resolution.target_schema_id	string \| null	可下钻目标论文。
items[].target_schema	object \| null	已解析目标论文卡片。
next_cursor	string \| null	下一页游标。

参数边界

单页: 1–100

说明

· 不要只统计有 target_schema_id 的项；完整 citation 数量以 total/Reference 为准。

GET/paper-schema/schemas/{schema_id}/citation-graph

论文间引用图谱

按 inbound/outbound、深度和节点上限扩展已解析的论文级 Citation Edge。

概述

只使用已解析的论文级 Citation Edge，从根论文向 outbound 或 inbound 扩展 1–3 跳，并返回可直接渲染的论文节点和边。未解析 Reference 不会被虚构成图节点。

适用场景

· 围绕种子论文构建小范围引用图。
· 分析语料内引用入边或出边。

不适用场景

· 它不是完整参考文献列表，也不能代表外部数据库的全部被引网络。

请求参数

字段	类型	必填	说明
schema_id	path string	必填	根论文主键。
direction	outbound\|inbound	可选	图扩展方向。默认 outbound
depth	integer	可选	扩展深度。默认 1范围 1–3
max_nodes / max_edges	integer	可选	图规模硬上限。默认 100 / 200范围节点 2–500，边 1–500

请求示例

curl "https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/citation-graph?direction=outbound&depth=1&max_nodes=100&max_edges=200" \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
root_schema_id / direction	string	根节点与扩展方向。
nodes	array<object>	schema_id、论文卡片和可用状态。
edges	array<object>	source_schema_id、target_schema_id、citation_count 等。
levels	array<object>	每层 frontier 和新增边统计。
truncated	boolean	是否达到节点或边上限。

参数边界

深度: 最多 3
节点/边: 各最多 500

说明

· truncated=true 时应缩小深度或分批围绕选定节点继续扩展。

Evidence & Content

检索公式、表格、结果、资源和引用语义等结构证据，并按需把证据或结构对象定位回论文原文。

POST/paper-schema/evidence/search

结构证据检索

按公开证据类别和关键词检索公式、表格、结果、比较、资源与引用语义。

概述

搜索经过 hot 策略保留的高价值结构证据。必须选择 1–5 个公开 groups，并至少提供 schema_ids、query、key、path_bucket、数值或布尔条件之一，以避免无边界扫描。

适用场景

· 查论文中的公式、表格结果、方法比较和代码/数据资源。
· 在一组论文中定位 citation signal 或实验结果证据。

不适用场景

· 完整 Entity 用 entities；正文任意关键词用 search-in-schema。

请求参数

字段	类型	必填	说明
groups	array<string>	必填	evidence_score、schema_unit、reference_semantics、reference_core、comparison_detail、citation_signal、formula、core_claim_result、table_evidence、resource。范围 1–5
group_operator	any\|all	可选	多个 group 的组合方式。默认 any
schema_ids	array<string>	可选	限定论文范围。范围最多 100 个
query / key / path_bucket	string	可选	文本、属性键或路径桶条件。
value_number_min / value_number_max / value_bool	number / boolean	可选	结构化值筛选。
hydrate_schema_papers	boolean	可选	是否附带论文卡片。默认 false
size / cursor	integer / string	可选	分页参数。默认 20 / null范围 1–100

请求示例

{
  "groups": ["formula", "table_evidence"],
  "group_operator": "any",
  "schema_ids": ["SCHEMA_ID"],
  "query": "accuracy",
  "size": 20
}

响应结构

字段	类型	说明
items[].evidence_id	string	公共 Evidence 主键。
items[].groups / key / value_*	array / scalar	证据分类、属性名和规范化值。
items[].source_entity_id / source_relation_id	string \| null	来源结构对象。
items[].provenance	array<object>	原文定位信息。
next_cursor	string \| null	下一页游标。

参数边界

groups: 1–5
单页: 1–100

说明

· Evidence 检索只返回公开证据合同中的规范化字段和定位信息。

GET/paper-schema/schemas/{schema_id}/evidence/{evidence_id}

证据详情

读取一条 Evidence 的规范化值、来源对象和 provenance。

概述

按 schema_id 和 evidence_id 精确读取一条结构证据，返回规范化值、公开分类、来源 Entity/Relation 引用和 provenance。

适用场景

· 搜索结果点击后查看证据完整值。
· 从证据继续回溯来源 Entity、Relation 或正文。

不适用场景

· 不提供未清洗的抽取负载或整篇原文。

请求参数

字段	类型	必填	说明
schema_id / evidence_id	path string	必填	论文与 Evidence 主键。

请求示例

curl https://api.sciverse.space/paper-schema/schemas/SCHEMA_ID/evidence/EVIDENCE_ID \
  -H "Authorization: Bearer ${SCIVERSE_API_TOKEN}"

响应结构

字段	类型	说明
evidence	object	group、key、value_text/value_number/value_bool 等公开值。
source	object	来源 Entity 或 Relation 标识。
provenance	array<object>	marker、paragraph_id 等定位信息。

参数边界

作用域: 单篇论文单条 Evidence

说明

· 不存在或不属于该 schema_id 的 evidence_id 返回 404。

POST/paper-schema/resolve-provenance

原文位置回溯

根据 marker 或 paragraph_id 定位原文段落及有限相邻上下文。

概述

把 Evidence、Entity 或 Relation 中保存的 marker/paragraph_id 解析成原文段落。请求必须二选一：schema_id + marker_nums，或者 paragraph_ids；window 控制相邻上下文。

适用场景

· 验证结构化结论是否被原文支持。
· 在界面中高亮证据段落及上下文。

不适用场景

· 没有任何定位信息时请改用 search-in-schema。

请求参数

字段	类型	必填	说明
schema_id + marker_nums	string + array<int>	可选	marker 是 Evidence 或结构对象返回的论文内不透明定位编号；调用方应原样传回。范围最多 100 个 marker
paragraph_ids	array<string>	可选	按全局 paragraph_id 定位；与 marker 模式二选一。范围最多 100 个
window	integer	可选	每个命中前后相邻段落数。默认 0范围 0–5
max_segments	integer	可选	总返回段落上限。默认 40范围 1–100

请求示例

{
  "schema_id": "SCHEMA_ID",
  "marker_nums": [12, 13],
  "window": 1,
  "max_segments": 20
}

响应结构

字段	类型	说明
segments	array<object>	paragraph_id、section、text、marker 和邻接位置。
trace.mode	marker\|paragraph_id	实际定位模式。
missing	array	未能解析的 locator。

参数边界

locator: 最多 100
上下文窗口: 0–5

说明

· 只返回有限段落上下文，不返回整篇论文。

POST/paper-schema/search-in-schema

单篇论文正文检索

在指定论文正文中执行关键词检索并返回匹配内容及位置；适用于调用方尚未持有 marker 或 paragraph_id 的情况。

概述

在一篇已知论文的正文中执行受限关键词检索，是 provenance 定位信息缺失时的补充查找方式。可用 section_hint、URL/代码偏好和上下文窗口缩小结果。

适用场景

· 根据指标名或资源名在单篇正文中定位上下文。
· Evidence 没有 marker 时进行补充查找。

不适用场景

· 跨论文全文检索使用 agentic-search；结构对象检索使用 Entity/Evidence。

请求参数

字段	类型	必填	说明
schema_id	string	必填	论文主键。
query	string	必填	正文关键词。范围 1–500 字符
section_hint	string	可选	优先章节。范围最多 300 字符
prefer_url / prefer_code	boolean	可选	资源检索偏好。默认 false
top_k / window	integer	可选	命中数和上下文窗口。默认 5 / 1范围 top_k 1–20，window 0–5

请求示例

{
  "schema_id": "SCHEMA_ID",
  "query": "source code repository",
  "prefer_url": true,
  "top_k": 5,
  "window": 1
}

响应结构

字段	类型	说明
segments	array<object>	命中段落和有限上下文。
segments[].score	number	单篇正文内相关性。
trace	object	查询方式和耗时。

参数边界

top_k: 1–20
window: 0–5

说明

· 结果只在指定 schema_id 内排序，不能与其他论文分数直接比较。

POST/paper-schema/hydrate-items

批量补充原文上下文

最多为 50 个 Entity、Relation 或 Evidence 项批量补充原文段落。

概述

批量把多个结构项的 paragraph_ids、marker_nums 或 fallback query 转换为原文上下文。服务优先使用精确 locator；没有 locator 时才执行单篇 search-in-schema。

适用场景

· 一次为材料包中的多个 Evidence 补齐原文。
· 减少逐项 resolve-provenance 请求。

不适用场景

· 不用于批量获取完整论文正文。

请求参数

字段	类型	必填	说明
items	array<HydrateItem>	必填	每项含 schema_id，以及 paragraph_ids、marker_nums 或 hydration_query。范围 1–50
window	integer	可选	上下文窗口。默认 1范围 0–5
max_segments_per_item	integer	可选	单项段落上限。默认 5范围 1–20
prefer_url_or_code	boolean	可选	fallback 搜索是否偏好 URL/代码。默认 false

请求示例

{
  "items": [
    {"schema_id": "SCHEMA_ID", "paragraph_ids": ["PARAGRAPH_ID"]},
    {"schema_id": "SCHEMA_ID", "hydration_query": "training setup"}
  ],
  "window": 1,
  "max_segments_per_item": 5
}

响应结构

字段	类型	说明
items[].hydration_method	paragraph_id\|marker\|schema_local_search\|none	每项采用的补全方式。
items[].segments	array<object>	补全后的原文段落。
items[].reason	string \| null	未补全原因。

参数边界

批量项: 最多 50
单项段落: 最多 20

说明

· 单项失败不会丢弃其他项；调用方应逐项检查 hydration_method 和 segments。

Research Materials

对已知论文按研究目标组合有限材料；它是任务导向的裁剪结果，不替代 Entity、Relation 或 Evidence 的完整列表接口。

POST/paper-schema/materials

研究材料包

按 overview、survey、benchmark、method 或 reproduction 目标返回论文元数据、Entity、内部 Relation、Evidence、关键词和可选引用上下文，并逐类标注 total、returned 与 truncated。

概述

面向已知论文按研究目标组合有限材料。goal 决定优先 Entity、Relation 和 Evidence 类型；返回结果是可直接交给 Skill/LLM 的裁剪包，不替代任何完整列表接口。

适用场景

· 为论文概览、综述、Benchmark 对比、方法分析或复现准备上下文。
· 批量为最多 20 篇已知论文生成结构摘要。

不适用场景

· 需要完整 Entity/Relation/Evidence 时应调用对应基础接口并分页。

请求参数

字段	类型	必填	说明
schema_ids	array<string>	必填	目标论文。范围 1–20
goal	overview\|survey\|benchmark\|method\|reproduction	可选	材料选择策略。默认 overview
include_relation_context	boolean	可选	是否补齐 Relation 两端 Entity 摘要。默认 false
per_schema_entity_limit	integer	可选	每篇 Entity 上限。默认 40范围 0–150
per_schema_relation_limit	integer	可选	每篇 Relation 上限。默认 40范围 0–150
per_schema_attribute_limit	integer	可选	每篇 Evidence 上限。默认 60范围 0–200
per_schema_term_limit	integer	可选	每篇内部关键词上限。默认 20范围 0–100

请求示例

{
  "schema_ids": ["SCHEMA_ID"],
  "goal": "reproduction",
  "include_relation_context": true,
  "per_schema_entity_limit": 60,
  "per_schema_relation_limit": 60,
  "per_schema_attribute_limit": 100
}

响应结构

字段	类型	说明
items[].schema_paper	object	论文元数据卡片。
items[].entities / relations / evidence / terms	array	按 goal 选取的有限结构材料。
items[].counts.<resource>.total	integer	该论文资源完整总数。
items[].counts.<resource>.returned	integer	本次实际返回数。
items[].counts.<resource>.truncated	boolean	是否因上限被裁剪。

参数边界

论文: 最多 20
单篇 Evidence: 最多 200

说明

· 只要 truncated=true，就不能把当前数组解释为该论文的完整结构集合。

请求中的常见字段

以下字段只适用于包含它们的具体操作；每个子操作的必填项和范围以展开后的合同为准。

字段	类型	必填	说明
schema_id	string	可选	Paper Schema 论文主键；在 /schemas/{schema_id} 等路径中为必填。
cursor	string	可选	分页接口返回的不透明游标；仅在继续翻页时原样传回，不得解析或自行构造。

响应结构

字段	类型	说明
schema_id	string	论文规范主键。
items / nodes / edges	array	当前接口返回的结构对象、证据或图数据。
next_cursor	string \| null	下一页游标；为空表示没有下一页。
partial	boolean	true 表示一个或多个依赖步骤失败或降级，但响应仍包含可用结果；必须结合 warnings 判断是否补查。
truncated	boolean	true 表示查询正常完成，但结果达到当前接口的数量、图规模或材料包上限。
warnings	array<string>	解释依赖降级、部分结果或其他需要调用方处理的情况。

错误码

错误码	信息	说明
400/422	INVALID_REQUEST	请求参数不满足对应操作的收窄条件或范围限制。
401	UNAUTHORIZED	Token 无效、已禁用或缺失。
403	FORBIDDEN	Token 有效，但账号未开通 Paper Schema 或没有所请求字段的权限。
404	NOT_FOUND	schema_id、Entity、Relation 或 Evidence 不存在。
429	RATE_LIMITED	账号、paper-schema 资源或调用来源配额已用尽；读取 retry_after。
502/503	UPSTREAM_UNAVAILABLE	结构查询服务不可用或繁忙，可按 request_id 重试。
504	PAPER_SCHEMA_TIMEOUT	结构查询超时；缩小图谱深度、批量范围或结果上限后重试。

通用错误码请参考「错误码」章节。

参数边界

限制项	值
默认速率限制	paper-schema 资源默认 30 请求 / 分钟 / 用户；实际值可由账号规则覆盖。
日调用配额	与其他公开 API 共用账号日配额；具体额度以控制台和账号权限为准。
计量范围	全部 /paper-schema/* 操作统一计入 paper-schema 资源，同时日志保留真实操作路径。
单次请求容量	每个操作另有 size、depth、max_nodes、max_edges、批量数等容量限制，以展开后的操作合同为准。

重试建议

· 502/503/504 可使用带随机抖动的指数退避，例如 1s、2s、4s，最多重试 3 次。
· 429 应优先读取 Retry-After 或错误体中的 retry_after（单位：秒）；不要立即并发重试。
· 400/401/403/404 不应自动重试，应先修正参数、Token、权限或资源 ID。
· GET 操作和使用稳定请求体的 POST 操作可安全重试；同一逻辑请求应复用相同 X-Request-ID，并在客户端另行记录 attempt 序号。
· HTTP 200 且 partial=true 不是完整成功；请读取 warnings 决定是否补查。

FAQ

为什么目录里只有一个 paper-schema 入口？

它是一套独立领域 API，但所有结构、证据和图谱操作共享同一鉴权、配额与统计资源，因此目录只展示一个一级入口。

引用图会包含全部引用吗？

不会。citations 返回完整 resolved/unresolved 引用；citation-graph 只返回能够连接到目标 schema_id 的已解析边。

如何完成综述、Benchmark 或复现等场景？

先用 paper-schema/search 或相关论文接口确定 schema_id，再调用 materials 并选择 survey、benchmark、method 或 reproduction goal；需要完整对象时继续使用基础 Entity、Relation 与 Evidence 接口。

partial 与 truncated 有什么区别？

partial=true 表示依赖步骤失败或降级但仍有可用结果，应读取 warnings；truncated=true 表示请求正常完成，只是结果达到数量或图规模上限，应分页或缩小范围继续查询。

说明

· 目录和流量统计只把这一组能力计为 paper-schema 一个一级资源。
· 综述、Benchmark、方法比较、论文复现、论文简报和主题图谱通过基础接口与 Materials profiles 组合完成，不需要额外的场景接口。

还没有 API Key？

登录控制台「密钥」即可创建。同一套 API Key 可用于已开通的 Sciverse、点石与 Skills 能力，提供基础试用额度，具体以账号权限为准。

前往控制台