PlantAI-dev/docs/API_USAGE.md

bbav20311 API 使用文档

版本: 1.0
日期: 2026-03-12
功能: 多数据库 API 查询（参考 ClawBio gwas-lookup 模式）

---

📚 目录

1. 快速开始
2. 支持的 API
3. 基础使用
4. 高级用法
5. 配置管理
6. 常见问题

---

快速开始

1. 导入模块

from gfa_core.api_clients import (
    MultiAPIQuery,
    PlantCAREClient,
    PfamClient,
    NCBIClient,
    EnsemblPlantsClient,
)

2. 简单查询示例

# 创建查询管理器
query = MultiAPIQuery()

# 查询基因信息
results = query.query_all('gene', {
    'gene_symbol': 'SPL',
    'organism': 'Arabidopsis'
})

# 生成统一报告
report = query.generate_unified_report(results, 'gene', 'SPL')
print(report)

---

支持的 API

植物数据库

API	功能	需要 API Key
PlantCARE	启动子顺式元件分析	❌ 否
Pfam	蛋白质家族查询	❌ 否
NCBI	基因/序列查询	⚠️ 可选
Ensembl Plants	植物基因组/表达	❌ 否
Phytozome	比较基因组学	⚠️ 可选
TAIR	拟南芥数据库	⚠️ 需要
PlantTFDB	转录因子数据库	❌ 否

API Key 申请地址

• NCBI: https://www.ncbi.nlm.nih.gov/account/
• Phytozome: https://phytozome-next.jgi.doe.gov/
• TAIR: https://www.arabidopsis.org/

---

基础使用

1. 启动子分析（PlantCARE）

from gfa_core.api_clients import PlantCAREClient

# 创建客户端
client = PlantCAREClient()

# 分析启动子序列
promoter_seq = "ATGCGATCGATCGATCG..."
result = client.analyze_promoter(promoter_seq)

# 查看结果
print(f"发现 {result['total_elements']} 个顺式元件")
print(f"分类: {result['categories']}")

# 查看具体元件
for category, elements in result['elements_by_category'].items():
    print(f"\n{category}:")
    for elem in elements:
        print(f"  - {elem.name}: {elem.sequence}")

2. 蛋白质家族查询（Pfam）

from gfa_core.api_clients import PfamClient

# 创建客户端
client = PfamClient()

# 搜索蛋白质结构域
domains = client.search_protein("Q9C5U0")  # UniProt ID

for domain in domains:
    print(f"{domain.accession}: {domain.name}")
    print(f"  {domain.description}")

# 获取家族详细信息
family_info = client.get_family_info("PF03110")  # SBP family
print(f"蛋白质数量: {family_info['protein_count']}")

3. NCBI 基因查询

from gfa_core.api_clients import NCBIClient

# 创建客户端（可选传入 API key）
client = NCBIClient(api_key="your_api_key_here")

# 搜索基因
genes = client.search_gene("SPL", "Arabidopsis")

for gene in genes:
    print(f"{gene.symbol}: {gene.description}")
    print(f"  染色体: {gene.chromosome}")
    print(f"  位置: {gene.location}")

# 获取序列
sequence = client.get_sequence("nuccore", "NM_001318947.1")
print(sequence[:200])  # 前200bp

4. 多 API 并行查询

from gfa_core.api_clients import MultiAPIQuery

# 创建查询管理器
query = MultiAPIQuery(max_workers=5, timeout=30)

# 查询类型和参数
query_type = 'protein'  # 'gene', 'protein', 'promoter', 'domain'
params = {
    'protein_id': 'Q9C5U0',
    'gene_symbol': 'SPL1',
}

# 执行并行查询
results = query.query_all(query_type, params)

# 生成统一报告
report = query.generate_unified_report(results, query_type, 'SPL1')

# 查看结果摘要
print(f"成功: {report['summary']['successful']}")
print(f"失败: {report['summary']['failed']}")

# 查看合并数据
print(report['merged_data'])

---

高级用法

1. 自定义查询配置

from gfa_core.api_config import get_api_config

# 获取 NCBI 配置
config = get_api_config('ncbi')
print(f"Rate limit: {config.rate_limit}s")
print(f"Timeout: {config.timeout}s")

# 创建带自定义配置的客户端
from gfa_core.api_clients import NCBIClient
client = NCBIClient(
    api_key="your_key",
    rate_limit=0.1  # 10 requests/second
)

2. 批量查询

from gfa_core.api_clients import MultiAPIQuery

query = MultiAPIQuery()

gene_list = ['SPL1', 'SPL2', 'SPL3', 'SPL4', 'SPL5']

for gene in gene_list:
    results = query.query_all('gene', {
        'gene_symbol': gene,
        'organism': 'Arabidopsis'
    })
    
    report = query.generate_unified_report(results, 'gene', gene)
    print(f"{gene}: {report['summary']}")

3. 错误处理

from gfa_core.api_clients import MultiAPIQuery, APIResult

query = MultiAPIQuery()
results = query.query_all('gene', {'gene_symbol': 'UNKNOWN_GENE'})

for api_name, result in results.items():
    if result.status == 'success':
        print(f"✅ {api_name}: 成功")
    elif result.status == 'error':
        print(f"❌ {api_name}: 错误 - {result.error_message}")
    elif result.status == 'timeout':
        print(f"⏱️ {api_name}: 超时")

---

配置管理

配置文件位置

config/api_config.yaml

配置示例

# NCBI API
ncbi:
  api_key: "your_ncbi_api_key_here"
  rate_limit: 0.1  # 有 key 时 10 req/s

# 通用设置
settings:
  default_rate_limit: 1.0
  request_timeout: 30
  max_retries: 3
  max_workers: 5

环境变量

也可以通过环境变量设置 API key：

export NCBI_API_KEY="your_key_here"
export PHYTOZOME_API_KEY="your_key_here"
export TAIR_API_KEY="your_key_here"

---

常见问题

Q1: 为什么某些 API 查询很慢？

A: 可能原因：

1. 网络延迟（API 服务器在国外）
2. 速率限制（特别是 NCBI 无 API key 时 3 req/s）
3. 查询复杂度高

解决：

• 申请 API key 提高速率
• 使用 MultiAPIQuery 并行查询
• 增加超时时间：timeout=60

Q2: PlantCARE 为什么无法连接？

A: PlantCARE 网页版没有公开 REST API，当前实现使用：

1. 本地元件模式匹配
2. 已知元件数据库（G-box, ABRE, W-box 等）

解决：如需完整功能，建议本地部署 PlantCARE 数据库。

Q3: 如何添加新的 API？

A: 步骤：

1. 在 gfa_core/api_clients/ 创建新客户端
2. 继承基类模式（参考 ncbi_client.py）
3. 在 __init__.py 导出
4. 在 multi_api_query.py 添加查询逻辑

Q4: API key 安全吗？

A:

• ✅ 存储在本地配置文件
• ✅ 支持环境变量（推荐用于服务器）
• ✅ 不会上传到代码仓库（.gitignore）
• ⚠️ 不要硬编码在代码中

---

参考

• ClawBio gwas-lookup: https://github.com/ClawBio/ClawBio/tree/main/skills/gwas-lookup
• NCBI E-utilities: https://www.ncbi.nlm.nih.gov/books/NBK25501/
• Ensembl REST API: https://rest.ensembl.org/
• Pfam: https://pfam.xfam.org/

---

文档版本: 1.0
最后更新: 2026-03-12