| --- |
| 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) |
|
|
