Villion GEO Audit：为AI搜索引擎优化而生的自动化结构化数据审计工具

一个基于FastAPI的开源GEO（生成式引擎优化）审计原型，能够自动分析网页元数据并生成JSON-LD结构化数据建议，帮助网站提升在ChatGPT、Google AI Overviews、Perplexity等AI搜索引擎中的可见性。

生成式引擎优化（GEO）是一门新兴的优化学科，其核心目标是让AI驱动的搜索引擎能够准确读取、理解、引用和总结网页内容。与传统SEO主要面向人类用户和关键词排名不同，GEO更关注机器可读性——尤其是如何让大语言模型在生成回答时能够自信地引用你的内容。

GEO的主要实现机制是结构化数据（Structured Data），特别是JSON-LD格式的Schema.org标记。这些嵌入在网页区块中的机器可读代码块，能够精确描述页面中的实体类型——无论是Organization（组织）、Article（文章）、Product（产品）还是FAQPage（常见问题页面）。对于AI爬虫和语言模型而言，JSON-LD提供了一种比解析原始HTML更可靠、更标准化的内容理解方式。

然而，大多数网站在GEO方面的投入严重不足。许多站点要么完全缺失结构化数据，要么使用了过时或错误的Schema标记。手动审计一个网站的GEO健康状况是一项极其繁琐的工作——这正是Villion GEO Audit试图解决的问题。

Villion GEO Audit采用清晰的分层架构，每个模块职责单一，便于独立替换或升级。项目基于Python 3.9+和FastAPI构建，核心依赖包括httpx（异步HTTP客户端）、BeautifulSoup4（HTML解析）和Pydantic（数据验证）。

Villion Aduit/
├── main.py              # FastAPI应用：HTTP路由和请求处理
├── schemas.py           # Pydantic模型：输入验证和响应结构
├── requirements.txt     # Python依赖
├── services/
│   ├── scraper.py       # 网页抓取：httpx + BeautifulSoup
│   └── llm_generator.py # Schema生成逻辑（当前为模拟实现）
├── templates/
│   └── index.html       # Jinja2前端模板
└── static/
    └── styles.css       # UI样式（玻璃拟态设计）

整个数据流非常直观：用户提交URL → 异步抓取目标页面 → 提取元数据（标题、描述、H1/H2标题、图片、字数）→ 基于规则选择Schema类型 → 生成JSON-LD推荐 → 返回结构化响应。这种流水线设计使得每个环节都可以独立优化，例如将scraper.py替换为Playwright以支持JavaScript渲染，或将llm_generator.py接入真实的LLM API。

开发团队考虑过Flask（简单熟悉但缺乏原生异步支持）、Django（功能全面但过于重量级）和FastAPI（原生异步、自动生成Swagger文档、一流的Pydantic集成）。最终选择FastAPI的关键原因在于GEO审计本质上是I/O密集型操作——使用httpx抓取远程页面时，异步支持意味着服务器不会因为等待网络响应而阻塞。此外，FastAPI自动生成的/docs Swagger界面让CTO或评审人员无需编写任何客户端代码即可立即测试API。

对于HTML抓取，团队评估了requests（同步阻塞）、httpx + BeautifulSoup（异步轻量）和Playwright（支持JavaScript渲染但体积约100MB、速度慢2-5秒/页）。最终选择httpx + BeautifulSoup作为原型方案，因为绝大多数内容丰富的可索引页面（博客、产品页、公司网站）都是服务器端渲染或在构建时注入meta标签。Playwright对于原型来说过于重量级，会显著拖慢请求周期。重要的是，scraper模块被有意隔离在services/scraper.py中，生产环境中替换为Playwright只需修改这一个文件。

这是项目中最重要的设计决策。团队采用了一种务实的混合方法：

• Schema类型选择：Article vs FAQPage基于H2标题数量判断——H2标题通常对应FAQ风格的章节。这种方法可靠、免费、即时且可解释。
• 标题和描述字段：直接从抓取的和<meta name="description">标签提取——确定性提取，无幻觉风险。</li> <li><strong>业务实体类型推断</strong>：规则无法可靠区分SaaS产品落地页和博客，但LLM阅读H1 + 前500字正文可以正确分类并选择SoftwareApplication、Product或Organization而非通用Article。</li> <li><strong>缺失描述的生成</strong>：当meta description不存在时，LLM可以从页面内容生成简洁准确的描述。</li> <li><strong>FAQPage答案填充</strong>：基于规则的模拟实现使用占位文本填充答案，而LLM可以阅读H2下方的实际正文内容并生成真实答案。</li> </ul> <p>这种设计反映了核心洞察：LLM在需要非结构化人类推理的地方增加价值（内容分类、生成散文），而对于可以精确提取的字段（标题、URL、日期、作者），正则表达式或CSS选择器总是更快、更便宜、更准确。</p>

规范要求返回"至少一个检测到的图片URL"，但页面上的图片范围从主视觉横幅（高价值）到1×1追踪像素（无价值）。项目采用优先级策略：首先检查——这是页面所有者明确选择代表其内容的图片，也是社交平台和AI爬虫使用的图片；如果缺失，则遍历标签，返回第一个非base64数据URI且src长度非平凡的图片。这避免了将追踪像素URL或1字节间隔GIF作为"检测到的图片"返回。

尽管规范允许"小型Next.js/React页面"或"清晰结构的API响应视图"，团队选择了Jinja2服务端模板。理由是：对于旨在演示后端能力的原型，添加完整的React/Next.js应用会引入构建工具、包管理器、CORS配置和部署复杂性，而这些对功能毫无增益。Jinja2模板在服务端渲染并返回完整HTML，CTO评审原型时关心的是数据质量，而非React是否hydrate了页面。UI通过玻璃拟态CSS实现了真正优质的视觉效果。