项目已开源： https://github.com/LANawa/url-content-analyzer
开源目的： 主要面向想 研究、学习如何调用 API 的开发者——大模型 API、前后端 API、REST 接口三条线，跑通一套可运行的完整示例
技术栈： FastAPI · Streamlit · httpx · DeepSeek API（OpenAI 兼容）
关键词： API 调用、大模型接口、REST API、httpx、OpenAI 兼容、FastAPI

一、这个项目适合谁？

如果你正在学：

• 怎么 申请 API Key、配置环境变量、发 HTTP 请求
• 怎么调用 大模型 API（DeepSeek / 智谱等 OpenAI 兼容接口）
• 怎么让 前端页面调用自己的后端 API
• 怎么设计 REST API，并用 curl / Postman / Python 调用

那这个项目就是为你准备的。

它表面上是一个「输入网页链接 → 自动总结」的工具，但源码里藏了三条清晰的 API 调用链路，你可以边看边改、边调边学：

学习主题	对应代码	你会学到什么
调用大模型 API	backend/services/llm_service.py	Bearer 鉴权、JSON 请求体、解析 LLM 返回
前端调用后端 API	frontend/app.py	用 httpx 发 POST、处理状态码与异常
对外提供 REST API	backend/main.py	FastAPI 路由、请求/响应模型、Swagger 文档

二、三条 API 调用链路（学习重点）

2.1 链路一：调用大模型 API（DeepSeek）

本项目使用 DeepSeek 的 OpenAI 兼容接口，换智谱、通义等同类服务时，通常只需改 .env 里的 LLM_BASE_URL 和 LLM_MODEL。

第一步：配置 Key（不要写进代码）

# .env
LLM_API_KEY=your_deepseek_api_key_here
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat

backend/config.py 通过 pydantic-settings 自动读取，代码里用 settings.llm_api_key 访问。

第二步：构造 HTTP 请求

核心逻辑在 llm_service.py，本质是向 /chat/completions 发 POST：

endpoint = f"{settings.llm_base_url.rstrip('/')}/chat/completions"
payload = {
    "model": settings.llm_model,
    "messages": [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_msg},
    ],
    "temperature": 0.3,
}

resp = httpx.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {settings.llm_api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=90.0,
)
resp.raise_for_status()
data = resp.json()
content = data["choices"][0]["message"]["content"]

学习要点：

• 鉴权：Authorization: Bearer <API_KEY> 是绝大多数 LLM 接口的通用写法
• 请求体：model + messages（system / user 角色）是 Chat Completions 标准格式
• 响应解析：从 choices[0].message.content 取文本，再 json.loads 得到结构化结果
• 降级策略：未配置 Key 或调用失败时，自动退回规则摘录，主流程仍可跑通

---

2.2 链路二：前端调用后端 API（Streamlit → FastAPI）

Streamlit 页面不直接调大模型，而是调用 本项目的 FastAPI 后端，这是典型的「前端调自己的 API」模式。

frontend/app.py 中的关键代码：

API_BASE = "http://127.0.0.1:8000"

resp = httpx.post(
    f"{API_BASE}/api/v1/analyze",
    json={"url": url.strip(), "force_refresh": force_refresh},
    timeout=120,
)

if resp.status_code == 200:
    data = resp.json()
    # 展示 summary、key_points 等字段
else:
    detail = resp.json().get("detail", "未知错误")

学习要点：

• 前后端分离：前端只关心 JSON 接口，后端封装抓取 + LLM 逻辑
• 错误处理：httpx.ConnectError 表示后端没启动；非 200 状态码读 detail 字段
• 超时：分析网页可能较慢，timeout=120 避免过早断开
• 可替换前端：同一套 API 可接 Vue、React、小程序，不必绑死 Streamlit

---

2.3 链路三：对外 REST API（给别人 / 给 Agent 调用）

后端 backend/main.py 暴露了标准 REST 接口，启动后可直接打开 Swagger 文档：

High Performance Web Crawler API - Swagger UI

方法	路径	说明
GET	/health	健康检查，查看 DB、LLM 是否就绪
POST	/api/v1/analyze	核心：提交 URL 进行分析
GET	/api/v1/analyze/{id}	按 ID 查询单条记录
GET	/api/v1/history	分页查询历史记录

请求示例：

POST /api/v1/analyze
{
  "url": "https://example.com/article",
  "force_refresh": false
}

响应示例：

{
  "id": 1,
  "url": "https://example.com/article",
  "content_type": "article",
  "title": "示例标题",
  "summary": "这篇文章主要介绍了……",
  "details": {
    "key_points": ["要点一", "要点二"],
    "text_length": 3200,
    "llm_used": true
  },
  "status": "success",
  "created_at": "2026-06-25T12:00:00"
}

用 Python 调用自己的 API：

import httpx

resp = httpx.post(
    "http://127.0.0.1:8000/api/v1/analyze",
    json={"url": "https://example.com", "force_refresh": False},
    timeout=120,
)
print(resp.status_code, resp.json())

学习要点：

• FastAPI 自动生成 OpenAPI / Swagger，方便调试
• 请求/响应用 Pydantic 模型校验（schemas/request.py、schemas/response.py）
• 这套接口可直接被 LangGraph Agent、自动化脚本、其他服务 复用

三、完整业务流程

    理解业务有助于你知道「为什么要这样调 API」：

用户输入 URL（Streamlit）
    ↓
前端 httpx POST → /api/v1/analyze（FastAPI）
    ↓
后端抓取网页正文（httpx / Playwright）
    ↓
后端 httpx POST → DeepSeek /chat/completions（大模型 API）
    ↓
解析 JSON → 写入 SQLite → 返回给前端展示

四、系统架构

┌─────────────────────────────────────────┐
      Streamlit 前端 (8501)                
      httpx 调用后端 API                   
└──────────────────┬──────────────────────┘
                   │ POST /api/v1/analyze
┌──────────────────▼──────────────────────┐
      FastAPI 后端 (8000)                 
      对外 REST API + 业务编排             
└──────┬───────────────┬──────────────────┘
       │               │
┌──────▼──────┐  ┌─────▼─────────────┐
   网页抓取          DeepSeek API      
   httpx 等         POST /chat/...   
└─────────────┘  └───────────────────┘
                       │
              ┌────────▼────────┐
                  SQLite 缓存    
              └─────────────────┘

---

五、项目目录（学 API 先看这些文件）

url-content-analyzer/
├── backend/
│   ├── main.py                 # ★ REST API 路由定义
│   ├── config.py               # ★ .env 读取 API Key
│   ├── schemas/                # 请求/响应 JSON 结构
│   └── services/
│       ├── llm_service.py      # ★ 大模型 API 调用（重点）
│       └── analyze_service.py  # 业务编排：抓取 → 调 LLM → 存库
├── frontend/
│   └── app.py                  # ★ 前端 httpx 调后端（重点）
├── .env.example                # API Key 配置模板
├── requirements.txt
├── start.bat                   # Windows 一键启动
└── README.md