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

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

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-04-17T15:57:15.000Z
- 最近活动: 2026-04-17T16:19:21.258Z
- 热度: 159.6
- 关键词: Ollama, LLM, SEO, 代理, Excel, 本地部署, 自动化, 产品目录
- 页面链接: https://www.zingnex.cn/forum/thread/local-llm-seo-agent-ollamaseo
- Canonical: https://www.zingnex.cn/forum/thread/local-llm-seo-agent-ollamaseo
- Markdown 来源: ingested_event

---

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

## 项目概述

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

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

## 核心功能架构

### 1. 演示与作业场景

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

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

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

### 2. Excel 目录 SEO 增强管道

这是项目最具实用价值的功能模块。它能够自动处理 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 服务正常运行：

```bash
# 拉取默认模型
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}
```

### 安装依赖

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

### 运行演示场景

```bash
# 健康检查（验证模型配置）
python -m app.main health

# 运行所有预设场景
python -m app.main demo

# 运行单个场景
python -m app.main demo --scenario calculator

# 自定义任务
python -m app.main demo --task "Calculate (345 + 55) * 3"
```

### 交互式聊天模式

```bash
python -m app.main chat
```

在聊天模式下，用户可以输入自然语言指令，如：
- "Calculate (12 + 8) * 4"
- "Read samples/test.txt and count the lines"
- "Open samples/products.xlsx, sheet products, and tell me how many data rows it has"

需要注意的是，聊天模式是无状态的，每次消息都是独立任务，代理不会保留对话历史。

### 目录处理管道

```bash
# 基本用法
python -m app.main process-catalog --input samples/products.xlsx --sheet products

# 自定义输出路径和限制处理行数
python -m app.main process-catalog \
  --input samples/products.xlsx \
  --output results/products_result.xlsx \
  --sheet products \
  --limit 5
```

## 技术亮点与工程实践

### 1. 本地优先架构

项目完全基于本地部署的 Ollama 模型，无需调用外部 API，这对于处理敏感的商业数据尤为重要。同时，本地运行也意味着零 API 费用和更低的网络延迟。

### 2. 健壮的错误处理

- 当模型返回无效 JSON 时，系统会尝试一次自动修复
- 行级处理失败不会中断整个管道运行
- 输入工作簿被完整保留，结果写入新文件，避免数据丢失

### 3. 可配置性

- CLI 基于 click 构建，提供清晰的命令结构和帮助信息
- 环境变量通过 python-dotenv 加载
- YAML 运行时配置支持复杂业务规则定义

### 4. 缓存机制

象征意义查询结果会被缓存到本地 JSON 文件，避免重复请求外部服务，提升处理速度并降低网络依赖。

## 当前限制与未来方向

根据项目文档，当前版本存在以下已知限制：

- 聊天模式不具备真正的对话记忆能力
- Excel 相关问题仍然依赖模型正确选择工具参数
- `read_text_file` 对绝对路径的处理较为宽松
- 象征意义 HTTP 查询是轻量级实现，主要内容仍来自词典默认值

测试覆盖方面，项目包含针对 CLI、演示场景和目录处理功能的测试用例，最新测试结果显示 19 个通过、2 个跳过。

## 应用场景与价值

local-llm-seo-agent 特别适合以下场景：

1. **电商运营**：批量生成产品 SEO 元数据，提升搜索引擎可见性
2. **内容管理**：自动化处理产品目录，减少人工编辑工作量
3. **数据隐私敏感场景**：所有处理在本地完成，无需上传商业数据到第三方服务
4. **教育演示**：展示 ReAct 代理架构的工作原理和实现方式

## 总结

local-llm-seo-agent 是一个设计精良、实用性强的本地 LLM 代理项目。它将大语言模型的推理能力与结构化的工具调用相结合，既提供了易于理解的演示场景，又包含了可直接投入生产的目录处理管道。对于希望探索本地 LLM 应用开发、或需要自动化 SEO 内容生成的团队来说，这是一个值得深入研究和使用的开源项目。