POST/agentic-search

agentic-search 智能检索与片段返回

用自然语言提问，返回最相关的可引用文献段落。

概述

agentic-search 面向 LLM Agent 与 RAG 场景。每条结果包含标题、正文片段、doc_id 和页码/位置等来源信息，适合快速找到可引用的上下文；需要读全文时，可用 doc_id 继续调用 content。

适用场景

· RAG 应用：为 LLM 补充含引用的文献证据
· Agent 工具调用：一屏拿到可回链的片段与原文位置
· 问答系统：结合文献原文与片段生成带出处的回答

不适用场景

· 精确 DOI、标题或字段化分页导出，请优先使用 meta-search。
· 读取完整原文上下文，请使用返回的 doc_id 继续调用 content。
· 下载图表或附件资源，请使用 resource。

鉴权

统一使用 API Key Bearer Token 鉴权，详见统一鉴权章节。在 HTTP Header 中加入：

Authorization: Bearer YOUR_API_TOKEN

请求示例

curl -X POST https://api.sciverse.space/agentic-search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "graphene battery cycle stability",
    "top_k": 10,
    "filters": {
      "lang": "en",
      "publication_published_year": {"gte": 2020},
      "topics": {
        "logic": "and",
        "dimensions": {
          "primary_topic_domain": "Physical Sciences"
        }
      }
    }
  }'

请求体（JSON）

字段	类型	必填	说明
query	string	必填	你的检索问题；不能为空。范围最大 4096 字符
top_k	integer	可选	返回片段数量。默认 10范围 1–100
sub_queries	integer	可选	查询改写数量，0 表示不改写。默认 0范围 0–4
filters	object	可选	按文献元数据收窄语义检索范围；字段结构见 filters 字段表。默认 {}

filters 字段表

字段	类型	值	说明
字段组合规则	rule	字段间 AND；同字段数组值 OR	不传 filters 或传 {} 表示不过滤。
lang	string	en、zh 等语言代码	文献语言。
title	string	标题字符串	按标题精确匹配。
author	string / string[]	作者名；数组表示任一作者命中	按作者名过滤。
publication_venue_name_unified	string	Nature、Science 等	按规范化发表载体名称过滤。
publication_venue_type	string	journal、conference、book series、repository 等	按发表载体类型精确匹配，传值不区分大小写。
publication_published_date	string / range	YYYY、YYYY-MM、YYYY-MM-DD、{gte,lte}、[min,max]	按发表日期过滤。
publication_published_year	number / range	2024、{gte:2020,lte:2025}、[2020,2025]	按发表年份过滤。
citation_count	number / range	100、{gte:100}、[100,null]	按被引次数过滤。
influential_citation_count	number / range	10、{gte:10}、[10,null]	按高影响力被引次数过滤。
topics.logic	string	and、or；默认 or	控制 topics.dimensions 中多个主题维度的组合方式。
topics.dimensions.primary_topic	string	Machine Learning 等主题名	按主要主题名称过滤。
topics.dimensions.primary_topic_domain	string	Physical Sciences、Social Sciences、Health Sciences、Life Sciences	按主要主题所属领域过滤。

响应结构

字段	类型	说明
hits	array	命中片段列表。
hits[].chunk_id	string	片段 ID。
hits[].chunk	string	片段文本内容。
hits[].doc_id	string	所属文献 ID，可传给 /content 读取原文。
hits[].title	string	文献标题。
hits[].abstract	string	文献摘要。
hits[].score	float	相关度得分。
hits[].source_type	string	pdf / web 等来源类型。
hits[].offset	integer	片段在原文中的字符偏移（Unicode 码点数）。
hits[].page_no	integer	原文页码（仅 pdf 类有）。
hits[].model_name	string	用于打分的模型名。
hits[].model_version	string	模型版本。
hits[].lang	string	文献语言。
hits[].metadata_type	string	资源类型，如 paper、ebook。
hits[].author	array<string>	作者列表。
hits[].publication_venue_name_unified	string	发表载体名称。
hits[].publication_venue_type	string	发表载体类型。
hits[].publication_published_date	string	发表日期，格式为 YYYY-MM-DD。
hits[].publication_published_year	integer	发表年份。
hits[].citation_count	integer	被引次数。
hits[].influential_citation_count	integer	高影响力被引次数。
hits[].primary_topic	string	文献主要主题名称。
hits[].primary_topic_domain	string	文献主要主题所属领域。

响应示例

{
  "hits": [
    {
      "chunk_id": "c_8c1f...",
      "chunk": "Graphene-based cathodes exhibit improved cycle stability ...",
      "doc_id": "d_2a91...",
      "title": "Cycle stability of graphene composite cathodes",
      "abstract": "...",
      "score": 0.873,
      "source_type": "pdf",
      "offset": 18432,
      "page_no": 4,
      "model_name": "sciverse-retriever",
      "model_version": "v2.3",
      "lang": "en",
      "metadata_type": "paper",
      "author": ["Jane Doe", "John Smith"],
      "publication_venue_name_unified": "Nature",
      "publication_venue_type": "journal",
      "publication_published_date": "2023-06-15",
      "publication_published_year": 2023,
      "citation_count": 128,
      "influential_citation_count": 12,
      "primary_topic": "Energy Storage",
      "primary_topic_domain": "Physical Sciences"
    }
  ]
}

错误码

错误码	信息	说明
400	INVALID_REQUEST	请求参数错误，检查 query / top_k 等取值。
401	UNAUTHORIZED	鉴权失败，检查 Authorization 请求头。
429	RATE_LIMITED	触发账号配额限制，请等待限流窗口恢复或每日额度重置后重试。
500	INTERNAL_ERROR	服务错误，指数退避重试。
502/503	UPSTREAM_UNAVAILABLE	服务暂不可用，指数退避重试。

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

重试建议

· 建议重试：500 / 502 / 503
· 不应重试：400 / 401；429 请等待限流窗口恢复或每日额度重置

能力边界

· agentic-search 返回 semantic evidence retrieval 结果和 evidence chunk，不生成最终答案。
· query 最长 4096 字符；top_k 范围 1–100；sub_queries 范围 0–4。
· filters 是语义检索过滤对象，结构不同于 meta-search 的 FieldFilter 数组。
· 结果字段会按账号权限裁剪，调用方必须容忍字段缺失。

FAQ

agentic-search 会直接生成综述或回答吗？

不会。它只返回可引用的证据片段、doc_id 和位置线索，上层 Agent 或 RAG 应用负责生成答案。

如何从 evidence chunk 继续读取上下文？

使用命中的 doc_id、offset 等字段调用 content，按字符切片读取原文上下文。

返回片段能直接引用吗？

可以作为引用线索，但回答中应同时保留 doc_id、doi、chunk_id、offset 或页码等来源信息。

agentic-search 和 meta-search 如何选择？

自然语言科研问题和证据召回选 agentic-search；字段化筛选、排序、导出和 DOI 查询选 meta-search。

还没有 API Key？

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

前往控制台