Quick Start

Quick Start

事实来源：主仓 pr-88 @ a312645，CLI 见 src/souwen/cli/，API 见 src/souwen/server/，配置见 src/souwen/config/models.py。

10 分钟内从零跑通 SouWen 的 4 种入口：CLI、Python、HTTP API、Docker。每一步只展示能立刻看到结果的最小动作，深度配置和故障排查见各自的"接下来"链接。

flowchart LR
    Install[1. 安装] --> CLI[2. CLI 跑一次搜索]
    CLI --> Python[3. Python 调用]
    Python --> Server[4. 启动 API 服务]
    Server --> Docker[5. Docker 一键部署]
    Docker --> Next[6. 接下来]

Loading

---

0. 前置要求

项	要求
Python	≥ 3.10（项目用 X | Y 类型联合语法）
系统	macOS / Linux / Windows（Windows 推荐 WSL2）
磁盘	核心库约 80 MB；含 crawl4ai 等浏览器抓取依赖时 ~500 MB
必备凭据	零配置即可使用 ≥40 个免 Key 数据源；其余按 Config API Keys 按需添加

不想本地装 Python？直接跳到 §5 Docker。

---

1. 安装

按需选择 extras 组合，缺什么装什么。

# 最小：核心库 + CLI（约 80 MB）
pip install souwen

# API 服务 + TLS 指纹 + 网页搜索 + 反爬（推荐）
pip install "souwen[server,tls,web,scraper]"

# 全量（含 PDF / Crawl4AI / newspaper / readability / robots / MCP）
pip install "souwen[server,tls,web,scraper,pdf,crawl4ai,newspaper,readability,robots,mcp]"

Extra	用途	何时装
server	FastAPI + Uvicorn	跑 HTTP API / Web Panel
tls / scraper	curl_cffi 浏览器 TLS 指纹	用爬虫类源（baidu/google/bilibili/zhihu 等）
web	trafilatura 正文提取	用 builtin fetch provider
pdf	pymupdf4llm	解析论文 PDF
crawl4ai	无头浏览器	JS 重型页面（如 google_patents）
newspaper / readability	文章提取	新闻类页面
mcp	Model Context Protocol	接入 Claude Code / Cursor

完整列表见主仓 pyproject.toml 的 [project.optional-dependencies]。

---

2. CLI 跑一次搜索

# 学术论文：默认源 openalex,arxiv（免 Key）
souwen search paper "transformer" --limit 5

# 专利：默认 google_patents（免 Key，但是 scraper，建议配 WARP）
souwen search patent "quantum computing" --limit 5

# 网页：默认 duckduckgo,bing（免 Key）
souwen search web "python asyncio" --limit 10

# 抓取一篇页面正文（builtin 零配置）
souwen fetch https://example.com

# 列出 93 个源 + 当前可用状态（绿色=可用，黄色=缺 Key，红色=异常）
souwen sources

# 健康检查
souwen doctor

输出默认是 Rich 表格；脚本管道用 --json：

souwen search paper "diffusion model" --json | jq '.[].results[].title'

看到 souwen: command not found？检查 pip install 是否成功；如果用了 pipx，确认 pipx ensurepath 已运行。

接下来：CLI Reference 列出全部命令与参数。

---

3. Python 调用

import asyncio
from souwen.facade import search, search_all, fetch_content, archive_lookup

async def main():
    # 按 (domain, capability) 派发，limit 自动分发到每个默认源
    papers = await search("transformer", domain="paper", limit=5)
    web    = await search("python asyncio", domain="web", limit=5)

    # 跨域聚合：一次调用同时打 paper / web / knowledge
    mixed = await search_all("quantum", domains=["paper", "web", "knowledge"])

    # 抓取页面正文（零配置）
    page = await fetch_content(["https://example.com"], provider="builtin")

    # Wayback 历史快照
    snapshots = await archive_lookup("https://example.com")

    print(papers, web, mixed, page, snapshots)

asyncio.run(main())

也可以直接用更细的便捷入口：

from souwen import search_papers, search_patents, web_search

resp = await search_papers("graph neural network", per_page=10)
for r in resp[0].results:
    print(r.title, "—", r.doi)

数据模型（PaperResult / WebSearchResult / FetchResult / ...）见 Python API。

---

4. 启动 API 服务

souwen serve --host 0.0.0.0 --port 8000

启动后访问：

URL	用途
http://localhost:8000/docs	Swagger UI（OpenAPI 3.1）
http://localhost:8000/redoc	ReDoc 渲染
http://localhost:8000/panel#/	Web Panel（默认 souwen-google 皮肤）
http://localhost:8000/health	容器存活探针
http://localhost:8000/readiness	K8s readiness（仅本地检查）

最小调用：

curl "http://localhost:8000/api/v1/search/paper?q=transformer&per_page=5"
curl "http://localhost:8000/api/v1/search/web?q=python"
curl -X POST 'http://localhost:8000/api/v1/fetch' \
  -H 'Authorization: Bearer admin-secret' \
  -H 'Content-Type: application/json' \
  -d '{"urls":["https://example.com"]}'

⚠️ Admin 端点默认锁定——未设 admin_password 时 /api/v1/admin/* 一律 401。本地测试可临时设 SOUWEN_ADMIN_OPEN=1 开放（启动时会打 WARNING）。生产务必显式设置 SOUWEN_ADMIN_PASSWORD。

完整端点表见 HTTP API；三角色（Guest/User/Admin）认证模型见 Authentication and Roles。

---

5. Docker 一键部署

最小起步：

docker run -d --name souwen \
  -p 49265:49265 \
  -e SOUWEN_ADMIN_PASSWORD=change-me \
  -v souwen-data:/app/data \
  ghcr.io/blueskyxn/souwen

Docker 镜像默认监听 49265（区别于 souwen serve 默认的 8000）。验证：curl http://localhost:49265/health。

docker-compose.yml 模板（项目根目录就有一份）：

services:
  souwen:
    image: ghcr.io/blueskyxn/souwen
    ports:
      - "49265:49265"
    env_file: [.env]
    environment:
      - SOUWEN_ADMIN_PASSWORD=change-me
      # 启用 Cloudflare WARP（可选）
      # - WARP_ENABLED=1
      # - WARP_MODE=auto
    volumes:
      - souwen-data:/app/data
    restart: unless-stopped
volumes:
  souwen-data:

启动：

docker compose up -d
docker compose logs -f souwen

WARP 模式选择、HF Space / ModelScope 部署、反向代理：见 Deployment Guide 与 Network and WARP。

---

6. 接下来

你的下一步	去哪里
把搜索接到 AI Agent（Claude Code / Cursor）	MCP Integration
不知道选哪个源	Data Source Guide
配置 API Key 提升限流/质量	Config API Keys
用 Web 面板可视化管理	Web Panel
加自定义数据源（无需改主仓）	Plugin Development
反爬被卡 / 高风险源走代理	Network and WARP
排查 401 / 429 / 504	Troubleshooting
想理解整体架构	Architecture