local-llm-seo-agent：基于Ollama的本地SEO自动化代理

一个基于Ollama本地大模型的Python代理框架，支持思考-行动-观察循环的演示场景，以及Excel产品目录的SEO字段自动填充与增强。

local-llm-seo-agent 是一个基于 Python 的开源项目，它利用本地部署的 Ollama 大语言模型，构建了一个功能完整的代理系统。该项目由 realan 开发，主要面向两个核心应用场景：一是通过思考-行动-观察循环完成各类演示任务，二是对 Excel 产品目录进行自动化的 SEO 字段增强处理。

这个项目的独特之处在于它完全运行在本地环境中，无需依赖外部 API 服务，既保护了数据隐私，又降低了使用成本。默认使用 qwen3.5:4b 模型，但用户可以通过环境变量灵活配置其他本地模型。

项目内置了多个预设的演示场景，展示了代理系统如何通过迭代式的思考-行动-观察循环来完成复杂任务。这些场景包括：

• 计算器场景：执行数学运算，如计算 (345 + 55) * 3
• 文件读取场景：读取文本文件并统计行数等元数据
• HTTP 请求场景：发起网络请求获取外部数据

每个场景都遵循经典的 ReAct（Reasoning + Acting）模式：代理首先分析问题并制定计划，然后执行具体的工具调用，最后根据观察结果调整下一步行动，直至任务完成。

这是项目最具实用价值的功能模块。它能够自动处理 Excel 产品目录文件，为每一行产品数据生成完整的 SEO 元数据。处理流程包括：

• 数据规范化：自动标准化列标题，添加缺失的输出列
• 实体识别：基于 YAML 词典检测产品实体类型
• 尺寸分类：从标题、重量和高度信息中推断产品尺寸标签
• 象征意义查询：加载或获取产品的象征意义描述
• LLM 结构化输出：调用本地模型生成 SEO 关键词、标题、描述等字段

项目采用模块化的代码组织结构：

app/
├── main.py              # CLI 入口
├── agent/               # 代理核心逻辑
│   ├── prompts.py       # 提示词模板
│   ├── runner.py        # 执行引擎
│   └── schemas.py       # 数据模式定义
├── llm/                 # 大模型客户端
│   └── ollama_client.py # Ollama API 封装
├── tools/               # 工具集
│   ├── calculator.py    # 计算器
│   ├── file_tools.py    # 文件操作
│   ├── http_fetch.py    # HTTP 请求
│   ├── excel_tools.py   # Excel 处理
│   └── catalog_tools.py # 目录处理专用
└── services/            # 业务服务层
    ├── catalog_processor.py  # 目录处理管道
    └── symbolism_service.py  # 象征意义服务

项目实现了丰富的工具集来支持各类任务：

演示/聊天工具：

• calculator：数学计算，支持 numexpr 或 eval 回退
• read_text_file：文本文件读取
• http_get：HTTP GET 请求
• get_excel_info：获取 Excel 工作簿信息
• read_excel_row：读取指定行数据

目录处理专用工具：

• 实体类型检测（基于 YAML 别名词典）
• 尺寸分类（基于规则引擎）
• 基础标签生成
• 象征意义缓存管理
• 工作簿读写辅助函数

处理后的 Excel 文件会包含以下增强字段：

字段名	说明
entity_type	检测到的实体类型
entity_confidence	实体识别置信度
size_tag	尺寸分类标签
size_reason	尺寸分类依据
symbolism_summary	象征意义摘要
symbolism_source_note	象征意义来源
seo_keywords	SEO 关键词
seo_title	SEO 标题
seo_description	SEO 描述
product_description	产品描述
processed_status	处理状态
processed_error	错误信息（如有）

首先需要确保本地 Ollama 服务正常运行：

# 拉取默认模型
ollama pull qwen3.5:4b

# 启动 Ollama 服务
ollama serve

如果使用其他模型，可在 .env 文件中配置：

OLLAMA_MODEL=qwen3:0.6b
OLLAMA_ENDPOINT=http://localhost:11434/api/generate
OLLAMA_TIMEOUT_SEC=120
SYMBOLISM_LOOKUP_URL_TEMPLATE=https://httpbin.org/anything/symbolism?query={query}