Skip to content

Config API Keys

Jump to bottom
BlueSkyXN edited this page May 4, 2026 · 3 revisions

Config API Keys

事实来源：主仓 pr-88 @ a312645 的 src/souwen/config/models.py、docs/configuration.md、.env.example、souwen.example.yaml。

SouWen 的 93 个内置源里，40+ 个完全免 Key就能跑（默认配置即可）；其余按需配 Key。本页是"按场景配最少的 Key"指南，决策树带你只装真正需要的那几个。

0. 决策：你需要配几个 Key？

flowchart TD
    Q[你要做什么？]
    Q --> Pap[只做学术论文]
    Q --> Web[只做通用网页搜索]
    Q --> Pat[只做专利]
    Q --> Vid[要 YouTube]
    Q --> Soc[要 Twitter / Reddit]
    Q --> Fet[要高质量抓取]
    Q --> All[全功能 RAG/Agent]

    Pap --> P_Min[零配置：openalex+arxiv+crossref+pubmed+dblp 全免 Key]
    Pap --> P_Opt[可选：openalex_email · semantic_scholar_api_key 提速]
    Pap --> P_Need[必选：core_api_key · ieee_api_key · zotero_api_key+library_id]

    Web --> W_Min[零配置：duckduckgo+bing 免 Key]
    Web --> W_Need[要 SERP 质量：tavily · serper · serpapi 三选一]

    Pat --> Pa_Min[零配置：google_patents 爬虫，但建议+WARP]
    Pat --> Pa_Need[官方：uspto_api_key · epo_consumer_*  · cnipa_client_*]

    Vid --> V_Need[必选：youtube_api_key]
    Vid --> V_Opt[可选：bilibili_sessdata]

    Soc --> So_Need[必选：twitter_bearer_token · reddit_client_*]

    Fet --> Fe_Min[零配置：builtin · jina_reader · readability · newspaper]
    Fet --> Fe_Need[反爬绕过：firecrawl · scrapfly · zenrows 等]

    All --> A_Set[最常见组合：openalex_email + semantic_scholar + tavily + youtube + jina + serper]
Loading

1. 三种放 Key 的方式（任选其一）

方式 A：环境变量（推荐生产/容器）

export SOUWEN_OPENALEX_EMAIL=you@example.com
export SOUWEN_SEMANTIC_SCHOLAR_API_KEY=sxxxx
export SOUWEN_TAVILY_API_KEY=tvly-xxxx
export SOUWEN_ADMIN_PASSWORD=your-strong-password
souwen serve

环境变量名规则：SOUWEN_<FIELD_NAME_UPPER>（WARP 字段额外支持不带 SOUWEN_ 前缀的别名，方便 Docker entrypoint）。

方式 B：.env 文件（推荐本地开发）

复制项目自带模板：

cp .env.example .env
$EDITOR .env

.env 通过 python-dotenv 自动加载。

方式 C：YAML 配置（推荐多 Key 场景）

souwen config init
$EDITOR ~/.config/souwen/config.yaml

或在项目根放 souwen.yaml：

# souwen.yaml
openalex_email: you@example.com
semantic_scholar_api_key: sxxxx
tavily_api_key: tvly-xxxx
youtube_api_key: AIzaSy-xxx
jina_api_key: jina_xxx

# 服务端
admin_password: your-strong-password

# 频道级覆盖（高风险源走 WARP）
sources:
  google: { proxy: warp }
  baidu: { proxy: warp }
  google_patents: { proxy: warp }

优先级

环境变量 SOUWEN_*
   ↓ 覆盖
./souwen.yaml
   ↓ 覆盖
~/.config/souwen/config.yaml
   ↓ 覆盖
./.env
   ↓ 默认
内置默认值

2. 按需配 Key（按场景）

2.1 学术论文场景

最小（零配置就够）：

# 不用填任何 Key
# 默认源：openalex + arxiv + crossref + pubmed + dblp

推荐（提升礼貌访问 / 限流）：

openalex_email: you@example.com         # OpenAlex polite pool（强烈建议）
semantic_scholar_api_key: ...           # SS 提升限流，含 TLDR 摘要
pubmed_api_key: ...                     # PubMed 限流由 3 → 10 req/s

必需 Key（auth_requirement="required"，缺则源不出现在 /api/v1/sources）：

源 字段 申请页
core core_api_key https://core.ac.uk/services/api
ieee_xplore ieee_api_key https://developer.ieee.org/
zotero zotero_api_key + zotero_library_id (+ zotero_library_type) https://www.zotero.org/settings/keys
unpaywall unpaywall_email 任意有效邮箱

2.2 通用网页搜索场景

最小：默认源 duckduckgo,bing 全免 Key。

RAG/Agent 推荐（按预算二选一）：

# 平价：千次 ~$1
serper_api_key: ...                     # https://serper.dev
# 或
serpapi_api_key: ...                    # https://serpapi.com

# AI 增强 + 摘要：tavily 免费 1000 次/月
tavily_api_key: tvly-...                # https://tavily.com
exa_api_key: ...                        # https://exa.ai

# 中文场景
zhipuai_api_key: ...                    # 智谱 Web Search Pro
aliyun_iqs_api_key: ...                 # 阿里云通义晓搜

自建实例（隐私/自托管）：

searxng_url: http://localhost:8888      # 部署 SearXNG 后填
whoogle_url: http://localhost:5000      # 部署 Whoogle 后填
websurfx_url: http://localhost:8080

详见 Self Hosted Sources。

2.3 专利场景

最小：google_patents 免 Key（但是 scraper，建议 + WARP）。

官方权威：

源 字段（多字段须全配） 备注
uspto_odp uspto_api_key https://developer.uspto.gov/api
epo_ops epo_consumer_key + epo_consumer_secret OAuth client_credentials
cnipa cnipa_client_id + cnipa_client_secret 仅大陆 IP 可达——记得关 WARP
the_lens lens_api_token https://www.lens.org/
patsnap patsnap_api_key 智慧芽

2.4 视频场景

youtube_api_key: AIzaSy-...              # YouTube Data API v3，配额 10K/日
bilibili_sessdata: ...                   # 可选；启用高画质/字幕/高频

申请 YouTube Key：Google Cloud Console，启用 "YouTube Data API v3"。

2.5 社交场景

twitter_bearer_token: AAAA...            # X API v2 Basic 套餐起步
reddit_client_id: ...
reddit_client_secret: ...
facebook_app_id: ...
facebook_app_secret: ...
  • Twitter 需 Basic 套餐（约 $100/月）；可读 search 端点。
  • Reddit 在 https://www.reddit.com/prefs/apps 创建 App。
  • weibo / zhihu 是 scraper，免 Key，但建议代理。

2.6 抓取场景

零配置：builtin / readability / newspaper / jina_reader / arxiv_fulltext / wayback / deepwiki / mcp / crawl4ai / site_crawler 全部免 Key。

反爬强需求：

firecrawl_api_key: fc-...
scrapfly_api_key: ...
scrapingbee_api_key: ...
zenrows_api_key: ...
scraperapi_api_key: ...
apify_api_token: ...
cloudflare_api_token: ...                # Browser Rendering
cloudflare_account_id: ...
diffbot_api_token: ...

2.7 开发者场景

github_token: ghp_...                    # 可选，未鉴权 60 req/h，鉴权 5K req/h
stackoverflow_api_key: ...               # 可选，提升配额

2.8 企业办公

feishu_app_id: cli_...
feishu_app_secret: ...

需在 飞书开放平台 创建自建应用，开启"云文档"权限。

3. 服务端密码（强烈建议）

启动 HTTP API 时强烈建议设：

admin_password: your-strong-password
user_password: ~                         # 可选；只设 admin 也行
guest_enabled: false                     # 默认就是 false
trusted_proxies:                         # 反向代理后必须设
  - 10.0.0.0/8
  - 127.0.0.1
expose_docs: true                        # 生产建议改 false
cors_origins: []                         # 按需开放

未设 admin_password 时 /api/v1/admin/* 一律 401，除非显式 SOUWEN_ADMIN_OPEN=1（仅本地/CI）。

详细的 Guest/User/Admin 角色模型见 Authentication and Roles。

4. 验证 Key 配置

# 看哪些字段已生效（敏感字段脱敏）
souwen config show

# 配置侧的健康度（不发真实请求）
souwen doctor
souwen doctor --json | jq '.failed'

# 真实跑一次（轻量）
souwen search paper "test" -s openalex -n 1
souwen search web "test" -e tavily -n 1
souwen fetch https://example.com -p jina_reader

每个源配置成功后会出现在 souwen sources 中；缺必需 Key 的源会被过滤掉（/api/v1/sources 也不会返回）。

5. 频道级覆盖（进阶）

只让某个源走特殊配置，不影响其他源：

sources:
  tavily:
    api_key: tvly-yyy                    # 频道级 api_key 优先于 flat tavily_api_key
    params:
      search_depth: advanced             # 传给 Client 的额外参数
      include_raw_content: true
  duckduckgo:
    proxy: warp                          # 仅 DuckDuckGo 走 WARP
    http_backend: curl_cffi
  google_patents:
    enabled: false                       # 临时禁用
  openalex:
    headers:
      User-Agent: "MyApp/1.0 (mailto:me@example.com)"

7 个频道字段：enabled / proxy / http_backend / base_url / api_key / headers / params。详见 Config Source Channel。

6. 常见问题

Q: 我配了 tavily_api_key 但 souwen sources 没显示 tavily

  • 检查环境变量大小写：SOUWEN_TAVILY_API_KEY（不是 tavily_api_key）。
  • 用 souwen config show 看是否真的读进去；优先级是否被 ~/.config/souwen/config.yaml 覆盖了。
  • souwen doctor --json | jq '.sources[] | select(.name=="tavily")' 看完整状态。

Q: 只想用部分功能，不想装太多 extras

按需即可：

pip install souwen                      # 仅核心：免 Key 的所有 paper 源都能跑
pip install "souwen[tls,scraper]"       # 加爬虫（baidu/google/bilibili 等）
pip install "souwen[server]"            # 加 FastAPI Server

完整 extras 表见 Quick Start#1-安装。

Q: Docker 里怎么配 Key？

# docker-compose.yml
services:
  souwen:
    image: ghcr.io/blueskyxn/souwen
    env_file: [.env]                    # 推荐
    environment:
      - SOUWEN_ADMIN_PASSWORD=...
      - SOUWEN_TAVILY_API_KEY=...

或挂 souwen.yaml：

volumes:
  - ./souwen.yaml:/app/souwen.yaml:ro

详见 Deployment Guide。

Q: 怎么写"Key 在 Vault 里"的场景？

启动前用脚本注入环境变量即可——SouWen 不内置 Vault 集成，但所有字段都接受环境变量。

export SOUWEN_OPENALEX_EMAIL=$(vault kv get -field=email secret/souwen)
export SOUWEN_TAVILY_API_KEY=$(vault kv get -field=tavily_key secret/souwen)
souwen serve

7. 接下来

Last calibrated：2026-05-04 · 主仓 pr-88 @ a312645`

Home · Quick Start · Architecture · FAQ · Troubleshooting · Coverage Manifest · Contributing

权威技术文档以主仓 docs/ 与 src/ 为准。本项目仅供 Python 学习与技术研究使用，禁止用于违反法律法规或第三方服务条款的用途。

SouWen Wiki

首页 · GitHub · 主仓 docs

起步

教程

功能

操作指南

参考手册

排障

元

Clone this wiki locally