用 Sciverse 查找论文全文证据

从检索片段出发，定位并读取原文完整段落作为可引用证据

在 GitHub 查看

用户场景

Agent 通过 agentic-search 找到了相关片段，但需要更完整的上下文来确认论点或生成精确引用。

预估调用量

~3–8 次 API 调用

适用工具

agentic-searchcontent

调用链路

agentic-search→ doc_id + offset→ content(offset, limit)→ 全文证据

输入示例

Agent 已通过 agentic-search 获得 chunk："AlphaFold2 achieves atomic accuracy..."
doc_id: "由 agentic-search 返回的真实 ID"
offset: 12480

输出示例

{
  "text": "## Methods\n\nAlphaFold2 achieves atomic accuracy in protein structure prediction through a novel architecture combining...(完整段落 ~2000 字符)",
  "next_offset": 14480,
  "more": true
}

Agent Prompt 示例

当你需要验证或扩展一个文献片段时：
1. 使用 chunk 中的 doc_id 和 offset
2. 调用 content 接口读取该位置前后的完整段落
3. 确认原文是否支持你的论点
4. 如需更多上下文，使用返回的 next_offset 继续读取

分步实现

Step 1: 环境准备

安装依赖并配置环境变量

!pip install httpx
import os
os.environ["SCIVERSE_API_TOKEN"] = "sv-your-token-here"  # 替换为你的真实值

Step 2: 读取完整上下文

调用 content 接口，以 offset 为起点读取原文。响应字段为 text（非 content）

import os
import asyncio
import httpx

BASE = "https://api.sciverse.space"
TOKEN = os.environ["SCIVERSE_API_TOKEN"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

async def get_fulltext(doc_id: str, offset: int = 0, limit: int = 2000):
    """读取文档原文。返回 {text, next_offset, more}"""
    async with httpx.AsyncClient(timeout=30) as client:
        resp = await client.get(
            f"{BASE}/content",
            headers=HEADERS,
            params={"doc_id": doc_id, "offset": offset, "limit": limit}
        )
        resp.raise_for_status()
        return resp.json()

async def find_top_hit(query: str) -> dict:
    """Use agentic-search to get a real hit for the content example."""
    async with httpx.AsyncClient(timeout=30) as client:
        resp = await client.post(
            f"{BASE}/agentic-search",
            headers=HEADERS,
            json={"query": query, "top_k": 3},
        )
        resp.raise_for_status()
        hits = (resp.json().get("hits") or [])
        if not hits:
            raise ValueError(f"No papers found for query: {query}")
        return hits[0]

async def main():
    hit = await find_top_hit("AlphaFold2 protein structure prediction")

    # 向前偏移 300 字符以获取前文语境
    start = max(0, hit.get("offset", 0) - 300)
    result = await get_fulltext(hit["doc_id"], offset=start, limit=2000)

    print(f"Text length: {len(result['text'])} chars")
    print(f"Has more: {result['more']}")
    if result.get("next_offset"):
        print(f"Next offset: {result['next_offset']}")
    print(f"\
Content preview:\
{result['text'][:300]}...")
    return hit, result

hit, result = await main()

Step 3: 迭代读取全文（可选）

如果需要更多上下文，使用 next_offset 循环读取

async def read_full_document(doc_id: str, max_chars: int = 16000):
    """循环读取直到全文或达到字符上限"""
    full_text = ""
    offset = 0
    while len(full_text) < max_chars:
        result = await get_fulltext(doc_id, offset=offset, limit=4000)
        full_text += result["text"]
        if not result.get("more"):
            break
        offset = result["next_offset"]
    return full_text

async def main():
    # 使用上一步 agentic-search 返回的真实 hit
    text = await read_full_document(hit["doc_id"], max_chars=16000)
    print(f"Total document length: {len(text)} chars")

await main()

注意事项

content 接口响应字段是 text（不是 content），请注意区分
offset 是 Unicode 码点数，不是字节数
默认 limit=700 字符，建议传入 2000–4000 以减少调用次数
部分文档可能无全文（返回 404），需做异常处理
建议向前偏移 300–500 字符读取，以获取片段的前文语境

FAQ

什么时候需要读取全文上下文？

当检索片段不足以判断证据是否支持 claim 时，需要用 content 读取原文上下文。

输出证据时要保留什么？

至少保留 doc_id、offset、原文 quote、标题和年份。

content API 的作用是什么？

它根据 doc_id 和 offset 返回论文全文片段，用于核验语义证据。

如何避免断章取义？

应读取 quote 前后上下文，并在输出中说明证据支持范围。

下一步

还没有 API Key？

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

前往控制台