FastAPI Jina AI Demo

基于 FastAPI 和 Jina AI Reader API 的 Serverless 网页阅读服务。

项目简介

这是一个使用 FastAPI 框架开发的 Web 服务，集成了 Jina AI 的 Reader API，可以将网页 URL 转换为可读的文本内容。项目采用阿里云函数计算（FC3）进行 Serverless 部署。

主要功能

• ✅ 网页内容提取：通过 Jina AI Reader API 将网页转换为纯文本
• ✅ URL 格式验证：自动验证输入的 URL 格式
• ✅ 完善的异常处理：包含请求验证、超时、连接错误等异常处理
• ✅ Serverless 部署：支持阿里云函数计算部署

技术栈

• 框架: FastAPI 0.119.1
• 服务器: Uvicorn 0.38.0
• HTTP 客户端: Requests 2.32.5
• 数据验证: Pydantic 2.12.3
• 运行时: Python 3.12 (Custom Debian11)
• 部署: 阿里云函数计算 FC3

API 接口

1. 健康检查

GET /

响应示例:

{
  "message": "Hello World"
}

2. 网页阅读

POST /reader

请求体:

{
  "url": "https://example.com"
}

响应示例:

{
  "result": "网页的文本内容..."
}

错误码:

• 422: URL 格式错误
• 408: 请求超时
• 503: 服务不可用
• 502: 外部服务错误
• 500: 内部服务器错误

本地开发

1. 安装依赖

cd code
pip install -r requirements.txt

2. 配置环境变量

项目使用 .env 文件管理配置信息，特别是敏感的 API 密钥。

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填写你的 Jina AI API Token
# JINA_API_TOKEN=your_actual_token_here

重要提示：

• .env 文件包含敏感信息，已被 git 忽略，不会提交到仓库
• 必须设置 JINA_API_TOKEN 才能正常运行服务
• 可在 Jina AI 官网 获取 API Token

3. 运行服务

# 方式 1: 使用 main.py（推荐）
python main.py

# 方式 2: 使用 FastAPI CLI
fastapi run server.py

# 方式 3: 使用 Uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000

服务将在 http://localhost:8000 启动。

测试 API

# 健康检查
curl http://localhost:8000/

# 测试网页阅读
curl -X POST http://localhost:8000/reader \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Serverless 部署

本项目使用 Serverless Devs 工具部署到阿里云函数计算。

前置要求

• 安装 Serverless Devs
• 配置阿里云访问凭证

部署命令

# 部署到香港区域
s deploy

# 部署到其他区域（需修改 s.yaml 中的 region 配置）
# 可选区域: hongkong, beijing, shanghai, guangzhou, shenzhen, chengdu, nanjing, hangzhou, wuhan

配置说明

• 函数名称: jina-ai
• 运行时: custom.debian11
• 内存: 512 MB
• CPU: 0.5 核
• 超时时间: 10 秒
• 实例并发度: 10
• 使用 Layer: FastAPI Layer (版本 4)

项目结构

.
├── code/                   # 应用代码目录
│   ├── config.py          # 配置管理文件（集中管理所有配置）
│   ├── main.py            # 入口文件（支持函数计算环境变量）
│   ├── server.py          # FastAPI 应用主文件
│   ├── requirements.txt   # Python 依赖
│   ├── .env               # 环境变量配置（本地，不提交到 git）
│   └── .env.example       # 环境变量模板
├── .gitignore             # Git 忽略配置
├── s.yaml                 # Serverless Devs 配置文件
└── readme.md             # 项目说明文档

配置说明

环境变量配置

所有配置项都集中在 code/config.py 中管理，可通过环境变量或 .env 文件进行配置：

配置项	环境变量	默认值	说明
Jina AI API Token	JINA_API_TOKEN	-	必需，Jina AI 的 API 密钥
Jina API 地址	JINA_API_BASE_URL	https://r.jina.ai	Jina Reader API 基础地址
请求超时时间	JINA_REQUEST_TIMEOUT	10	API 请求超时时间（秒）
服务器主机	SERVER_HOST	0.0.0.0	服务器监听地址
服务器端口	SERVER_PORT / FC_SERVER_PORT	8000	服务器端口（函数计算优先使用 FC_SERVER_PORT）
日志级别	LOG_LEVEL	info	日志级别（debug/info/warning/error）
应用名称	APP_NAME	Jina AI Reader Service	应用名称
应用版本	APP_VERSION	1.0.0	应用版本号
调试模式	DEBUG	false	是否开启调试模式

函数计算部署配置

在阿里云函数计算部署时，需要在 s.yaml 的 environmentVariables 中添加：

environmentVariables:
  JINA_API_TOKEN: "your_jina_api_token"  # 替换为实际的 API Token
  PYTHONPATH: /opt/python:/code
  # ... 其他配置

注意事项

1. ✅ 已优化：敏感信息（API Token）已通过环境变量管理，不再硬编码在代码中
2. ✅ 已优化：.env 文件已加入 .gitignore，不会提交到 git 仓库
3. 函数计算会自动设置 FC_SERVER_PORT 环境变量，默认使用 8000 端口
4. 请求超时时间默认为 10 秒，可通过 JINA_REQUEST_TIMEOUT 环境变量调整
5. 使用了阿里云香港区域的 FastAPI Layer，其他区域需要相应调整 s.yaml

许可证

MIT