Tutorial First Search

Tutorial 01 · 第一次搜索

学习目标：跑通"搜论文 → 抓 PDF → 输出 JSON"的完整端到端，理解 SouWen 的三种入口。 前置：Python ≥ 3.10，零配置。 耗时：约 10 分钟。

我们会用全免 Key 的源（openalex / arxiv / jina_reader）完成一个最小研究助手。每步都标"如果出错"。

---

步骤 1：装最小集

pip install souwen
souwen --version

预期输出：souwen 1.1.x。

❌ souwen: command not found：检查 PATH（pipx ensurepath 或 venv 激活）。详见 Troubleshooting#1-启动失败。

---

步骤 2：CLI 跑一次搜索

souwen search paper "transformer attention" --limit 3

预期看到 Rich 表格：

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Title                                            ┃ Year ┃ Citations ┃ DOI                              ┃ Source   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Attention Is All You Need                       │ 2017 │ 80000+   │ 10.48550/arXiv.1706.03762        │ openalex │
...

❌ "Connection error"：检查网络是否能到 https://api.openalex.org。

---

步骤 3：JSON 输出 + jq

souwen search paper "transformer attention" --limit 3 --json | jq '.[].results[] | {title, doi, year}'

预期看到：

{ "title": "Attention Is All You Need", "doi": "10.48550/arXiv.1706.03762", "year": 2017 }
{ "title": "...", "doi": "...", "year": 2018 }
{ "title": "...", "doi": "...", "year": 2019 }

❌ jq: command not found：brew install jq / apt install jq，或省略后半段。

---

步骤 4：Python 调用 + 抓 PDF 全文

# tutorial.py
import asyncio
from souwen.facade import search, fetch_content


async def main():
    # 1) 搜 5 篇论文
    resp = await search("transformer attention", domain="paper", limit=5)
    items = resp[0].results if resp else []
    print(f"找到 {len(items)} 篇")

    # 2) 找第一篇有 DOI 的，用 jina_reader 抓全文
    for p in items:
        if p.doi:
            url = f"https://doi.org/{p.doi}"
            print(f"\n抓取: {url}")
            fetched = await fetch_content([url], provider="jina_reader", timeout=60)
            r = fetched.results[0]
            if r.error:
                print(f"  ❌ {r.error}")
                continue
            print(f"  ✓ 标题: {r.title}")
            print(f"  ✓ 字数: {len(r.content)}")
            print(f"  ✓ 前 300 字: {r.content[:300]}…")
            break


asyncio.run(main())

跑：

python tutorial.py

❌ jina_reader 抓不到（少数页面会拒绝）：换 provider="builtin" 或 arxiv_fulltext（针对 arXiv URL）。

---

步骤 5：可选——加 LLM 摘要

如果你有 OpenAI / DeepSeek / 自托管 OpenAI 兼容 Key：

# souwen.yaml（项目根）
llm:
  enabled: true
  api_base: https://api.deepseek.com/v1
  api_key: sk-xxx
  model: deepseek-chat
  timeout: 60

启动 API：

souwen serve --port 8000

调摘要：

curl -X POST -H "Content-Type: application/json" \
  -d '{"q":"transformer attention","domain":"paper","limit":3}' \
  http://localhost:8000/api/v1/summarize | jq .summary

❌ 503 service_unavailable：llm.enabled=false 或 llm.api_key 没配。详见 LLM Summary。

---

步骤 6：把整个流程串成 JSON 流水线

souwen search paper "RAG" --limit 3 --json \
  | jq -c '.[].results[] | {title, doi, year}' \
  > papers.jsonl

cat papers.jsonl | while read line; do
  doi=$(echo "$line" | jq -r .doi)
  if [ "$doi" != "null" ]; then
    echo "Fetching DOI: $doi"
    souwen fetch "https://doi.org/$doi" -p jina_reader --json \
      | jq '.results[0] | {url, title, content_format, snippet}'
  fi
done

---

你学到了什么

• SouWen 的三种入口（CLI / Python / HTTP API）走同一个门面层。
• 搜索默认用免 Key 的 openalex,arxiv，不需要任何配置。
• 抓取的默认 provider 是 builtin，但 jina_reader 通常效果更好（且免 Key）。
• 错误不外抛——抓取失败装进 result.error。
• JSON 输出 + jq 可以直接组合成数据管道。

---

接下来

• Tutorial AI Agent — 把 SouWen 接到 Claude Code / Cursor
• Tutorial Production — 部署到生产环境
• Data Source Guide — 怎么选更专业的源
• Config API Keys — 加 Key 解锁更多能力