Spaces:
Runtime error
Runtime error
| 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) | |