Markitdown API

一个基于 FastAPI 的简单 API 服务，用于将 HTML 内容转换为 Markdown 格式。其核心功能由 Microsoft Markitdown 库提供。

✨ 功能特性

• HTML 转 Markdown: 将 HTML 字符串转换为简洁的 Markdown。
• FastAPI 后端: 构建于高性能的 FastAPI 框架之上。
• 交互式文档: 通过 Swagger UI 自动生成 API 文档。
• 易于部署: 简单的安装和执行步骤，并提供 Docker 支持。

---

🚀 快速上手

按照以下说明在本地安装并运行项目。

环境要求

• Python 3.8+

安装与设置

1. 克隆仓库 (或下载文件):

   git clone <your-repository-url>
   cd markitdown-api

2. 创建并激活 Python 虚拟环境:

   • 在 Windows 上:

     python -m venv venv
     .\venv\Scripts\activate

   • 在 macOS/Linux 上:

     python3 -m venv venv
     source venv/bin/activate

3. 安装所需依赖:

   pip install -r requirements.txt

---

运行应用

在激活虚拟环境后，使用 Uvicorn 启动 API 服务：

uvicorn main:app --reload

服务将运行在 http://127.0.0.1:8000。--reload 参数会在代码变更后自动重启服务，非常适合开发环境。

---

🐳 容器化运行 (可选)

如果您的机器上安装了 Docker，可以更方便地使用容器来运行此应用。

使用 Docker

1. 构建 Docker 镜像:

   docker build -t markitdown-api .

2. 运行 Docker 容器:

   docker run -p 8000:8000 markitdown-api

使用 Docker Compose (推荐)

docker-compose 提供了更简单的命令来管理应用的生命周期。

1. 构建并启动服务:

   docker-compose up

   如果想在后台运行，请使用 -d 标志：

   docker-compose up -d

2. 停止并移除服务:

   docker-compose down

---

📖 API 使用说明

交互式 API 文档

测试 API 最简单的方式是使用自动生成的交互式文档。服务运行后，在浏览器中访问以下地址：

http://127.0.0.1:8000/docs

API 端点

POST /convert

将 HTML 字符串转换为 Markdown。

请求体 (Request Body):

{
  "html": "<your-html-string>"
}

curl 使用示例:

curl -X POST "http://127.0.0.1:8000/convert" \
-H "Content-Type: application/json" \
-d "{\"html\": \"<h1>标题</h1><p>这是一个包含<b>加粗</b>文本的段落。</p>\"}"

成功响应 (200 OK):

{
  "markdown": "# 标题\n\n这是一个包含**加粗**文本的段落。\n\n"
}