API 参考 - 目远AI

概览

Base URL

http://localhost:8000/api

部署到生产环境后换成你自己的域名。建议套一层 HTTPS 反向代理。

认证

在 config.yaml 里设置 api.auth_token 后，所有请求需要带 Bearer token：

Authorization: Bearer your-secret-token-here

不设 token 的话 API 默认无认证（适合本地开发）。生产环境请务必配置。

通用响应格式

{
  "status": "ok",
  "data": { ... },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "took_ms": 1234
  }
}

端点

POST /api/collect

触发一次数据采集任务。异步执行，返回任务 ID。

请求体

{
  "sources": ["sina_news", "eastmoney"],
  "filters": {
    "sector": "technology",
    "min_relevance": 0.6
  },
  "period": "24h",
  "max_articles": 200
}

响应 — 202 Accepted

{
  "status": "ok",
  "data": {
    "task_id": "task_8f3a2b1c",
    "sources": ["sina_news", "eastmoney"],
    "estimated_time_s": 45
  }
}

POST /api/analyze

对已采集的数据运行分析管道。可以指定分析模型和参数。

请求体

{
  "task_id": "task_8f3a2b1c",
  "model": "sentiment_v2",
  "options": {
    "enable_cross_validation": true,
    "min_confidence": 0.5
  }
}

响应 — 200 OK

{
  "status": "ok",
  "data": {
    "analysis_id": "ana_7e2d4f9a",
    "articles_processed": 47,
    "insights": [
      {
        "type": "trend",
        "sector": "technology",
        "direction": "bearish_short_term",
        "confidence": 0.78,
        "supporting_articles": 12,
        "sentiment_score": -0.32
      },
      {
        "type": "signal",
        "sector": "ai_infrastructure",
        "direction": "bullish_long_term",
        "confidence": 0.82,
        "supporting_articles": 8,
        "sentiment_score": 0.61
      }
    ]
  }
}

POST /api/advise

基于分析结果生成投资建议。

请求体

{
  "analysis_id": "ana_7e2d4f9a",
  "risk_level": "moderate",
  "horizon": "medium_term",
  "max_recommendations": 5
}

响应 — 200 OK

{
  "status": "ok",
  "data": {
    "summary": "科技板块短期承压，但 AI 基建方向中长期确定性高。",
    "recommendations": [
      {
        "action": "watch",
        "target": "算力基础设施",
        "confidence": 0.82,
        "risk": "medium",
        "reason": "三大运营商资本开支计划超预期，算力需求持续增长",
        "sources_count": 8
      },
      {
        "action": "hold",
        "target": "消费电子",
        "confidence": 0.71,
        "risk": "medium",
        "reason": "需求复苏信号不明确，等待 Q2 财报确认",
        "sources_count": 5
      }
    ],
    "generated_at": "2026-04-15T10:30:00Z"
  }
}

GET /api/status

查看系统状态和任务进度。

响应 — 200 OK

{
  "status": "ok",
  "data": {
    "version": "0.3.0",
    "uptime_s": 86421,
    "database": "connected",
    "redis": "connected",
    "active_tasks": [
      {
        "task_id": "task_8f3a2b1c",
        "type": "collect",
        "status": "running",
        "progress": 0.65,
        "started_at": "2026-04-15T10:28:00Z"
      }
    ],
    "stats": {
      "total_articles": 12847,
      "total_analyses": 342,
      "cache_hit_rate": 0.73
    }
  }
}

错误码

出错时响应格式：

{
  "status": "error",
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task task_xyz not found"
  }
}

HTTP 状态码	错误码	说明
400	INVALID_PARAMS	请求参数格式错误或缺少必填字段
401	UNAUTHORIZED	缺少或无效的 Bearer token
404	TASK_NOT_FOUND	指定的 task_id 或 analysis_id 不存在
409	TASK_ALREADY_RUNNING	相同参数的任务正在执行中
422	SOURCE_UNAVAILABLE	指定的数据源暂时不可用
429	RATE_LIMITED	请求频率超限，请稍后重试
500	INTERNAL_ERROR	服务端内部错误

Rate Limiting

默认限制：每个 token 每分钟 60 次请求。超限后返回 429 状态码。

响应头里会带上限速信息：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1713178200

X-RateLimit-Reset 是 Unix 时间戳，表示限速窗口重置的时间。

关于 /api/collect 的特殊限制：采集任务比较重，同一时间最多允许 3 个并发采集任务。超过后新请求会返回 TASK_ALREADY_RUNNING。这个限制和每分钟请求数是独立的。