---
title: Wellfound AI
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# Wellfound AI — Excel 数据补全工具

AI 驱动的自动化 Excel 数据补全工具，专为 Wellfound (AngelList Talent) 导出数据设计。通过 Web 抓取和 LLM API（OpenAI/DeepSeek）智能提取融资信息、公司联系方式和地址数据。

## 功能特性

- 🤖 **AI 深度网页理解**：使用 GPT-4o / DeepSeek 分析网页内容，提取结构化数据
- 📍 **智能地址处理**：自动识别美国总部/办事处地址，填入 location.apply 和 state.apply
- 📧 **多重联系方式获取**：全站扫描 HR/招聘邮箱、联系表单 URL、招聘页面链接
- 💾 **断点续处理**：保存进度，中断后可恢复继续
- 🔄 **实时 Excel 写入**：每行处理完立即写入，不怕中途崩溃
- ⚡ **并行处理**：可配置并发数，加速大规模数据处理

---

# 📖 完整部署指南：从零到上线 Hugging Face Spaces

> 本指南面向零经验用户。即使你从未使用过 Hugging Face，也能按步骤在 15 分钟内完成部署。

---

## 目录

1. [前置准备](#1-前置准备)
2. [创建 Hugging Face 账号](#2-创建-hugging-face-账号)
3. [创建 Space（在线工作区）](#3-创建-space)
4. [克隆代码到本地](#4-克隆代码到本地)
5. [上传项目到 Space](#5-上传项目到-space)
6. [等待构建 & 首次启动](#6-等待构建--首次启动)
7. [使用你的工具](#7-使用你的工具)
8. [常见问题](#8-常见问题)
9. [本地开发](#9-本地开发)

---

## 1. 前置准备

你需要准备：

| 事项 | 说明 |
|------|------|
| ✉️ 邮箱 | 用于注册 Hugging Face 账号 |
| 🔑 API Key | OpenAI API Key（[获取地址](https://platform.openai.com/api-keys)）或 DeepSeek API Key（[获取地址](https://platform.deepseek.com/api_keys)） |
| 📊 Excel 文件 | Wellfound 导出的数据文件（格式：Company Name, Location, Internal Link, External Link…） |
| 💻 电脑 | Windows / macOS / Linux 均可，需联网 |

> **不熟悉命令行？** 不用担心，Hugging Face 提供网页版 Git 上传，全程可视化操作。

---

## 2. 创建 Hugging Face 账号

### 步骤 2.1：注册

1. 打开浏览器，访问 **[https://huggingface.co/join](https://huggingface.co/join)**
2. 填写邮箱和密码，点击 **Sign Up**
3. 检查邮箱，点击验证链接
4. 完成个人资料设置（头像、用户名随意）

### 步骤 2.2：创建 Access Token（API 令牌）

上传代码时需要这个令牌验证身份。

1. 登录后，点击右上角头像 → **[Settings](https://huggingface.co/settings/tokens)**
2. 左侧菜单选择 **Access Tokens**
3. 点击 **Create new token**
4. Token type 选择 **`Write`**（可写权限）
5. Token name 填写 `wellfound-ai`（随意命名）
6. 点击 **Generate a token**
7. ⚠️ **立即复制保存** — 这个 token 只显示一次！

```
Token 示例: hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

## 3. 创建 Space

### 步骤 3.1：新建 Space

1. 访问 **[https://huggingface.co/new-space](https://huggingface.co/new-space)**
2. 填写配置：

| 配置项 | 填写内容 |
|--------|---------|
| **Space Name** | `wellfound-ai`（或自定义名称） |
| **License** | `mit` |
| **Space SDK** | 选择 **`Docker`** |
| **Docker Template** | 选择 **`Blank`**（空白模板） |
| **Space Hardware** | 选择 **`CPU basic`**（免费版） |
| **Visibility** | 选择 **`Public`**（公开）或 **`Private`**（私有） |

3. 点击 **Create Space**

> 🎉 页面会跳转到你的新 Space，此时显示 "Building..." — 别急，还没上传代码。

---

## 4. 克隆代码到本地

有两种方式获取本项目代码：

### 方式 A：直接下载 ZIP（推荐，无需 Git）

1. 从本项目仓库点击 **Code → Download ZIP**
2. 解压到任意文件夹，例如 `D:\wellfound-ai\`

### 方式 B：Git 克隆

```bash
git clone <本仓库地址> wellfound-ai
cd wellfound-ai
```

> 如果项目还没上传到 GitHub，可以直接使用方式 A。

---

## 5. 上传项目到 Space

### 方案一：网页端直接上传（最简单，推荐）

1. 打开你的 Space 页面（`https://huggingface.co/spaces/<你的用户名>/wellfound-ai`）
2. 点击顶部的 **Files** 标签
3. 点击 **Upload files** 按钮
4. 将以下文件/文件夹拖拽上传：

```
必须上传的文件 ✅
├── Dockerfile           # Docker 构建配置
├── app.py               # FastAPI 主程序
├── requirements.txt     # Python 依赖
├── core/                # 核心模块文件夹
│   ├── __init__.py
│   ├── excel_handler.py
│   ├── scraper.py
│   ├── ai_extractor.py
│   ├── address_processor.py
│   └── contact_finder.py
├── templates/           # 前端模板文件夹
│   └── index.html
├── static/              # 静态资源文件夹
│   └── style.css
├── .gitignore
└── .dockerignore
```

5. 上传后，在 Files 页面点击 **Commit** 保存

### 方案二：Git 命令行上传（需安装 Git）

```bash
# 1. 进入项目目录
cd wellfound-ai

# 2. 初始化 Git（如果是 ZIP 下载的）
git init
git add .
git commit -m "Initial commit"

# 3. 添加 HF Space 远程仓库
git remote add origin https://huggingface.co/spaces/<你的用户名>/wellfound-ai

# 4. 拉取 HF 远程仓库（处理可能的冲突）
git pull origin main --rebase

# 5. 推送代码
git push origin main

# 提示输入用户名时，填写你的 Hugging Face 用户名
# 提示输入密码时，填写第 2 步创建的 Access Token
```

---

## 6. 等待构建 & 首次启动

### 步骤 6.1：监控构建过程

1. 打开 Space 页面，观察 **Building** 状态
2. 点击 **Builder Logs** 查看实时构建日志
3. 构建大约需要 3-5 分钟（主要是安装 Chromium 浏览器）

**构建日志示例（正常情况）：**
```
Step 1/8 : FROM python:3.11-slim          ✅
Step 2/8 : RUN apt-get install ...         ✅
Step 3/8 : COPY requirements.txt .         ✅
Step 4/8 : RUN pip install ...             ✅
Step 5/8 : RUN playwright install ...      ✅ (这步最慢)
Step 6/8 : COPY app.py .                   ✅
Step 7/8 : RUN mkdir -p data/              ✅
Step 8/8 : CMD ["python", "app.py"]        ✅
```

### 步骤 6.2：确认运行

构建完成后，Space 状态从 **Building** 变为 **Running**（绿色圆点）。

1. 点击 **App** 标签查看运行界面
2. 你应该看到 Wellfound AI 的完整网页界面
3. 如果显示 "错误" 或空白，点击 **Logs** 标签查看运行时日志

---

## 7. 使用你的工具

### 操作步骤

```
┌─────────────────────────────────────────────┐
│  Step 1: 输入 API Key                         │
│  ├─ 选择 AI 服务（OpenAI / DeepSeek）          │
│  └─ 粘贴你的 API Key                          │
├─────────────────────────────────────────────┤
│  Step 2: 上传 Excel 文件                       │
│  ├─ 拖拽文件到上传区域                         │
│  └─ 确认文件列数和行数正确                      │
├─────────────────────────────────────────────┤
│  Step 3: 开始处理                             │
│  ├─ 设置起始行（断点续传用）                    │
│  ├─ 设置最大处理行数（0 = 全部）               │
│  └─ 点击 "Start Processing"                   │
├─────────────────────────────────────────────┤
│  Step 4: 下载结果                             │
│  └─ 处理完成后，点击 "Download" 按钮           │
└─────────────────────────────────────────────┘
```

### 数据流转

```
C 列 (Wellfound 内部链接)
  → Playwright 渲染页面
  → regex + AI 提取估值/轮次信息
  → 填入 Valuation / Rounds / Series / Total Raised

D 列 (公司官网)
  → Playwright 渲染页面
  → AI 深度扫描邮箱/地址/表单
  → 填入 contact / location.apply / state.apply

每行处理完 → 立即写入 Excel → 不怕中断
```

### API 费用预估

| 模型 | 每行成本 | 659行总成本 |
|------|---------|------------|
| GPT-4o | ~$0.01 | ~$6-10 |
| GPT-4o-mini | ~$0.001 | ~$1-2 |
| DeepSeek-Chat | ~$0.001 | ~$0.5-1 |

> 💡 建议先关闭 AI（只用 Web Scraping）处理几行测试流程，确认没问题再开启 AI。

---

## 8. 常见问题

### Q: 构建失败，日志显示 "playwright install" 错误？

A: 检查 **Space Hardware** 是否选择了 `CPU basic`（不是 `CPU upgrade`）。免费版有时内存不足导致 Chromium 安装失败，可以在 Dockerfile 的 playwright install 命令后加 `--with-deps`。

### Q: 应用运行了但页面打不开？

A: 确认 Dockerfile 中 `EXPOSE 7860` 和 README 头部的 `app_port: 7860` 一致。检查 Space 日志中有没有 `Wellfound AI - Server Starting` 字样。

### Q: API 调用总是超时？

A: HF Spaces 免费版的网络出口在海外，访问某些网站可能较慢。可以：
- 调大并发数（concurrency = 1）
- 使用 DeepSeek 替代 OpenAI（API 延迟更低）
- 考虑升级到 HF Pro 订阅

### Q: 如何设置 Space 为私密？

A: 在 Space Settings → **Visibility** 改为 **Private**。注意：免费版只能有一个私有 Space。

### Q: 如何更新已有 Space 的代码？

A: 修改代码后，在 Space 的 Files 页面重新上传覆盖，或 `git push` 即可。HF 会自动重新构建。

### Q: 数据安全吗？

A: 
- 上传的文件仅存储在 Space 容器内，不会公开
- 容器休眠后数据会清除（建议处理完立即下载）
- API Key 通过前端输入，不存储在服务端

---

## 9. 本地开发

在本地运行以进行调试和开发：

### 环境要求

- Python 3.9+
- Git

### 快速开始

**Windows:**
```bash
# 双击运行
start.bat
```

**macOS / Linux:**
```bash
chmod +x start.sh
./start.sh
```

**手动启动:**
```bash
# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 安装 Playwright 浏览器
playwright install chromium

# 3. 启动服务
python app.py

# 4. 浏览器打开
# http://localhost:7860
```

### Docker 本地构建

```bash
# 构建镜像
docker build -t wellfound-ai .

# 运行容器
docker run -p 7860:7860 wellfound-ai

# 打开 http://localhost:7860
```

---

## 项目结构

```
wellfound-ai/
├── app.py                    # FastAPI 主程序（6 个 API 端点）
├── Dockerfile                # Docker 构建配置（HF Spaces 用）
├── requirements.txt          # Python 依赖
├── .gitignore                # Git 忽略文件
├── .dockerignore             # Docker 构建忽略文件
├── start.bat / start.sh      # 本地一键启动
│
├── core/                     # 核心模块
│   ├── excel_handler.py      # Excel 读写 + 断点续传
│   ├── scraper.py            # Playwright 智能网页抓取
│   ├── ai_extractor.py       # AI 数据提取（OpenAI/DeepSeek）
│   ├── address_processor.py  # 智能地址处理
│   └── contact_finder.py     # 联系方式获取
│
├── templates/                # 前端模板
│   └── index.html            # 单页应用 UI
│
├── static/                   # 静态资源
│   └── style.css
│
└── data/                     # 运行时数据（不在 Git 中）
    ├── uploads/              # 上传的 Excel
    ├── results/              # 处理结果
    └── checkpoints/          # 断点续传状态
```

---

## 许可证

MIT License — 可自由使用、修改和分发。

---

## 技术支持

- 遇到问题？在 Space 页面点击 **Community** 标签发起讨论
- Hugging Face 官方文档：[https://huggingface.co/docs/hub/spaces](https://huggingface.co/docs/hub/spaces)