企业官网建设流程全解析

简介：本资源是面向旅游推荐系统开发者与数据科学学习者的GraphRag景区推荐系统完整Python实现方案，聚焦于利用图算法建模用户-景点关系，解决个性化、可解释的旅游目的地推荐难题。项目包含2000个文件，涵盖16个CSV（结构化景点与行为数据）、15个txt（日志与说明）、7个json（配置与元数据）、6个xml（系统参数）、4个py（核心算法与接口模块）及大量chat-xxx格式的对话缓存文件（共约1300个），体现其融合大模型交互与图检索的混合架构特点；压缩包仅97.31MB，轻量易部署。已有342人下载学习，适合希望掌握图神经网络在推荐场景落地、理解GraphRag技术原理、复现端到端景区推荐Pipeline的中高级开发者。 先把结论放在前头：如果想拿一个开箱即用的景区推荐系统，直接套传统协同过滤模板，大概率会踩到数据稀疏、冷启动、解释性差这三板斧；但如果你愿意多花两天时间，用Python把GraphRag这条链路跑通，得到的不只是一个推荐列表，而是一套能“说清楚为什么推荐”的景区知识图谱底座。

这篇文章我会按真实项目推进顺序来写：为什么选型GraphRag、GraphRag核心机制拆解、源码工程结构设计、从零跑通索引和查询的完整步骤、以及我在实操中遇到的各种坑和绕坑方案。内容偏工程落地，代码片段都来自我实际跑过的项目，配置参数给出的是经过验证的范围，不是说明书上的默认值。适合有Python基础、想尝试GraphRag做垂直领域应用（不限于景区）的开发者参考。

1. 为什么景区推荐系统我选了GraphRag而不是传统方案

1.1 传统推荐方案在景区场景下的三个硬伤

先聊聊景区推荐这个场景的特殊性。我们平时在网上看到的推荐系统教程，大部分围绕电商或内容平台展开，核心逻辑是“用户行为 → 物品相似度 → 预测打分”。电商场景下用户有清晰的购买记录、浏览时长、收藏行为，数据量大且行为信号密集。但景区推荐完全不是这么回事：一个用户可能一年才旅游一两次，整个行为数据稀疏到几乎没法算相似度矩阵；新景区上线没有用户评分，推荐系统只能干瞪眼；更麻烦的是，用户对景区推荐的诉求是“我这次想玩什么”，而不是“我上次看了什么”，意图和行为的耦合度极低。

传统协同过滤解决不了冷启动和意图理解，基于内容的推荐则卡在标签体系构建上——景区标签（如“亲子”“爬山”“历史古迹”）全靠人工维护，扩展性和覆盖度都有限。我也试过直接用向量RAG方案，把所有景区介绍切片后做embedding检索，效果倒是能跑通，但有一个致命问题：向量检索本质是文本相似度匹配，它能回答“跟这个景点相似的景点还有哪些”，却回答不了“带5岁孩子去杭州玩3天，预算5000，怎么安排最合理”这种需要跨实体推理的问题。因为答案藏在景点、交通、餐饮、天气、人群偏好这些不同维度的关系里，而单纯文本embedding编码不了这种结构化的关联。

1.2 GraphRag在这里解决的核心问题

GraphRag的思路是：先让LLM从原始文档里抽取出实体和关系，构建知识图谱，再通过社区发现算法把图谱切成不同层级的社群，最后为每个社群生成摘要。这样，查询到来时，系统既能用全局检索（对社区摘要做map-reduce回答）来回答宏观规划类问题，也能用局部检索（沿实体关系扩展）来回答具体景点关联类问题。

放到景区推荐场景里，这一套组合拳正好对症。全局检索擅长做什么？它能把“杭州三天亲子游”拆成“西湖、宋城、九溪烟树、自然博物馆”这些实体，再根据社区摘要给出路线、节奏、预算分布，推荐结果天然带原因。局部检索擅长做什么？当用户问“我不喜欢太商业化，西湖周边还有哪里值得逛”，系统沿着图谱里“西湖—茅家埠—浴鹄湾”的关系边做扩展，返回的是真正在图结构上存在关联的景点，而不是文本上“看起来像”的景点。

因为GraphRag把文本变成了图，景区的领域知识不再是躺在数据库里的一条条记录，而是一张可以被遍历和计算的关系网。推荐系统从“算相似度”升级成了“基于关系的推理”，这一步对整个领域来说是很本质的差异。

1.3 选型对比：GraphRag、向量RAG、传统推荐，我做了什么取舍

下面这张表是我做技术选型时整理的对比，保留在这里供参考。

我的结论是：如果目标系统已经有大量用户行为数据，且推荐对象相对标准化，传统推荐依旧是最划算的选择；如果只是想做一个“帮我查景点”的问答机器人，向量RAG足够；但如果你想做的是“能理解需求、能解释推荐理由、还能跨实体做规划”的景区推荐系统，而且预算允许调用GPT或Claude这类模型跑离线索引，GraphRag的投入产出比是明显更高的。

2. GraphRag运行机制拆解：索引流水线、图谱社区与两种检索模式

2.1 索引流水线：从景区文档到知识图谱

GraphRag的离线索引过程可以理解为一条自动化的大模型信息抽取流水线。我最初还以为它内部像Neo4j那样有一堆图谱算法，等真正读了源码才发现，图谱构建完全靠LLM一句一句地抽实体和关系。整条流水线大致经历这几个阶段：文档分块（chunking）→ 实体/关系抽取（entity and relationship extraction）→ 图谱数据聚合（graph clustering）→ 社区检测（community detection）→ 社区摘要生成（community summarization）。

这段链路里最容易被忽略的是分块策略。GraphRag默认把文档切成固定大小的chunk，我对景区介绍数据做实验时发现，chunk长度直接决定了实体抽取的完整性。切太大，LLM上下文占用高、抽取出无效关系的概率上升；切太小，一个景点的完整介绍被拆成好几块，实体“西湖”可能在第1块出现，而“断桥”“雷峰塔”等周边实体在第3块才出现，抽出来的关系图会稀疏很多。

我给出一组实测参考值：景区介绍类文档单个知识块建议在800～1200 token，重叠区域设300 token。这样既能保证一个实体多次出现的上下文交叉覆盖，又不会把上下文窗口撑得太满。具体到代码里，大概是这么配置的。

# config/settings.yaml 核心片段 chunks: size: 1200 overlap: 300 group_by_columns: - id

另外提醒一个细节：GraphRag对文档格式有要求，纯文本文件必须放在input目录下，编码建议UTF-8。我第一版用的是直接从数据库导出CSV，结果中文乱码折腾了半天，后来干脆统一转成txt，省事很多。

2.2 社区检测与分层摘要：为什么必须用Leiden算法

实体和关系抽取完，GraphRag会拿到一个巨大的图，节点是实体，边是关系。此时如果直接把整张图塞给LLM做摘要，Token消耗会非常吓人，也没法保证质量。所以GraphRag引入社区检测算法，将图中聚集紧密的节点划分为社区，并在每个社区内部生成摘要。这一步最核心的价值是“图压缩”：把海量实体关系聚合为可解释的语义单位，后续查询不必遍历全部节点。

社区检测算法选了Leiden，而不是更常见的Louvain。主要原因是Leiden能保证社区连通性且更稳定，对图结构细小的扰动不敏感。Louvain在图上做聚合时可能产生不连通的社区，导致摘要内容跳跃。从工程角度，Leiden对多层级社区的支持更好，GraphRag正是靠这种层级结构做不同粒度的查询召回。

社区摘要会按层级（level）保留，level越高、粒度越粗，覆盖的范围越大。我实际在景区数据上跑出来的效果是：level 0对应具体景点和近邻实体；level越往上，越接近“西湖景区整体”“杭州文旅资源”这类主题社区。全局检索本质是对这些社区摘要做map-reduce，而不是直接去图里跑路径，所以在一次面向复杂问题（如“从杭州到千岛湖一路有哪些适合带老人的景点”）的查询中，即使跨越多个社区，也能得到一个整合性的回答。

2.3 全局检索和局部检索，在什么时候用哪个

GraphRag官方提供了两种查询模型，理解它们的差异对最终推荐体验非常重要。

全局检索（Global Search）的思路是：把所有社区的摘要拼接成多个map块，分发给LLM做并行摘要，最后reduce成最终答案。它的优点是对全图的全局语义覆盖能力很强，适合回答“整体规划类”问题，比如“帮我把杭州5天4晚的行程排一下”“华东这一带适合亲子游的线路有哪些”。缺点是Token消耗大、单次查询延迟高，因为它本质上把整个社区的摘要都跑了一遍。

局部检索（Local Search）则相反：先定位到问题涉及的实体节点，然后沿实体关系向外扩展指定深度（默认是2跳），把相关子图、相关文本块、相关社区摘要一并取出来，组成一个局部上下文，再让LLM基于这个上下文作答。它的优点是快、省、精准，适合回答“具体场景类”问题，比如“西湖周边哪个景点人少且能看山水”“灵隐寺和法喜寺离得远吗”。

这里有一个非常容易被忽略的点：全局检索和局部检索不是简单的“一个宏观一个微观”，它们有一个本质区别——局部检索看到了真实的图谱结构，而全局检索只看到了社区摘要。我测试中发现，当问题包含明确实体（“西湖”这类），局部检索给出推荐明显更贴切；当问题模糊且宏观（“适合全家老小的华东线路”），全局检索因为覆盖了更多上下文，回答更有条理。工程上建议路线是先做意图判断，再选择检索模式，而不是盲目混用。

3. 实操过程：从零搭建基于GraphRag的景区推荐系统

3.1 环境准备与源码工程目录设计

先说环境。GraphRag要求Python 3.10到3.12之间，3.13及以上目前装包可能踩坑，我用的是3.11实测稳定。安装命令很简单。

pip install graphrag

注意graphrag这个包名很容易被认成别的库，务必确认装到了微软官方的graphrag。装完建议顺手安装lancedb，这是GraphRag默认的向量存储依赖，不显式装的话第一次跑索引会自动拉取，但容易因网络问题中断。

我建议的源码工程结构如下，既保持GraphRag的约定，也方便自己扩展推荐服务。

scenic_graphrag/ ├── config/ │ ├── settings.yaml # GraphRag索引参数 │ └── prompts/ # 覆盖默认提示词 ├── input/ # 存放景区原始文档 │ ├── hangzhou.txt │ ├── qiandao.txt │ └── ... ├── output/ # 索引产物 ├── src/ │ ├── data_loader.py # 数据导入 │ ├── index_pipeline.py # 索引流水线封装 │ ├── query_service.py # 推荐查询服务 │ ├── intent_router.py # 意图路由 │ └── recommender.py # 排序与推荐组装 └── tests/

这个结构把GraphRag的索引过程和业务查询逻辑解耦。索引跑完之后，query_service.py不直接调命令行，而是调用GraphRag的查询引擎API做二次封装，方便HTTP接口化。

3.2 景区数据准备：实体、关系、描述如何设计

GraphRag对原始文档不做强制schema约束，因为schema是LLM抽取出来的。但源文档的质量直接决定图谱质量，这个环节值得多花心思。

我设计景区数据时采用了每篇文档聚焦一个主题的策略。常用的文档结构包含以下几个部分：

• 景区基础信息：名称、所在城市、具体位置、开放时间、门票参考价
• 景区特色描述：自然景观、人文背景、核心景点（如断桥、雷峰塔）
• 旅游体验信息：适合人群、游玩时长建议、最佳季节、交通方式、餐饮住宿配套
• 周边关联：附近景点、联动路线、与周边城市的距离

举个例子，我当时准备的“西湖.txt”，开头就有这样一段：

杭州西湖风景名胜区位于浙江省杭州市西湖区龙井路1号，是国家5A级旅游景区。景区核心面积约6.38平方公里，主要景点包括断桥残雪、苏堤春晓、曲院风荷、平湖秋月、雷峰夕照等。西湖适合亲子游、情侣游、老年游，四季皆宜，建议游玩时间3至6小时，可乘坐地铁1号线至龙翔桥站后步行到达。周边景点包括灵隐寺、飞来峰、云栖竹径、宋城、九溪烟树。

这段文字看起来朴实，但它隐含的实体和关系非常密集：实体有“西湖”“龙井路”“断桥残雪”“苏堤春晓”“雷峰夕照”等，关系有“位于”“包含”“适合”“附近”等。GraphRag在抽取阶段会把这些关系构建成图结构。每个景点都按这种结构组织，图谱质量就会比较高。

3.3 settings.yaml关键参数配置：大模型选型、Token截断与向量存储

GraphRag的核心配置全部集中在settings.yaml文件，我用的是定制后的版本。下面贴出几个我认为最重要的配置段做了说明。

llm: api_key: ${GRAPHRAG_API_KEY} model: gpt-4o-mini model_supports_json: true requests_per_minute: 100 max_tokens_per_minute: 80000 chunks: size: 1200 overlap: 300 entity_extraction: prompt: prompts/entity_extraction.txt max_gleaning: 1 strategy: type: graph_intelligence community_detection: hierarchy_levels: 4 vector_store: type: lancedb

几个关键参数我逐一说明。

第一个是max_gleaning。这个参数控制LLM是否需要反复修正实体抽取结果。官方文档的解释比较抽象，我自己的理解是：gLEANING每次都会把上次抽取结果重新喂给LLM，让它自行检查有没有遗漏实体或关系。设为1就表示机会修正一轮，0则完全不修正。从经验上看，0和1的差异在景区场景下并不大，反而0能节省不少Token，除非源文档质量很差，否则我建议直接设0，先把成本控住。

第二个是hierarchy_levels。这个参数决定社区检测生成多少层级。设4对景区这个规模的数据量已经很充足，再多层级对查询响应的提升有限，只增加索引耗时。

第三个是vector_store。GraphRag默认向量存储是lancedb，对单机项目足够了，不需要额外部署服务器。如果团队已存在Milvus或Qdrant，可以通过GraphRag的存储配置对接，但我建议垂直领域先跑通单机，没必要一开始就上分布式。

3.4 跑通索引：命令、日志、验证三步走

初始化项目目录和执行索引的命令如下：

python -m graphrag.index --init --root ./scenic_graphrag python -m graphrag.index --root ./scenic_graphrag

第一次跑之前，记得在scenic_graphrag目录下创建.env文件，写入：

GRAPHRAG_API_KEY=sk-xxxx GRAPHRAG_LLM_MODEL=gpt-4o-mini

索引这一步是GraphRag里最耗时、费用最集中的环节。我拿近30个景区文档实测，chunk size设1200、gpt-4o-mini，大概需要12到15分钟。如果文档量增加到200篇，耗时和Token消耗会指数上升，所以一定要先把数据量控制在合理范围内。

索引跑完之后，output目录下会生成parquet文件和向量索引目录。我建议先查看stats子目录下的报表，确认文档分块数、实体数和关系数是否合理。如果实体数非常少，多半是chunk切分太大或提示词需要调整。

3.5 查询服务封装：命令行验证与意图路由设计

GraphRag官方命令行查询适合验证效果，入口如下：

python -m graphrag.query --root ./scenic_graphrag --method global "带5岁孩子去杭州玩3天，预算5000，行程怎么安排" python -m graphrag.query --root ./scenic_graphrag --method local "西湖周边有哪些人少且适合看自然风光的地方"

但推荐系统的核心不是查询，而是把查询结果转成可用的推荐列表。我在源码里设计了意图路由模块，把输入做轻量分类：

# src/intent_router.py import re def route_intent(query: str) -> str: if any(word in query for word in ["行程", "安排", "规划", "几天", "线路"]): return "global" if any(word in query for word in ["附近", "周边", "哪里", "推荐", "适合"]): return "local" return "global"

规则很简单，但实际体验提升明显。因为“宋城值得去吗”这种带明确实体的问题如果被路由到global，系统会去读社区摘要，推荐的不一定是用户想得到的“这个景点的评价”；路由到local后，系统会沿“宋城”这个实体做关系扩展，推荐结果明显更细致。

整体推荐逻辑最后落到recommender.py，它要做的事是把GraphRag返回的文本解析成结构化的候选景点，再按与用户需求的相关度排序。我的做法是让GraphRag先输出带景点名的推荐理由，然后代码里用关键词匹配抽出候选景点，再对候选景点做去重、过滤（比如预算、时间限制），最终输出带解释的推荐列表。实际效果比直接让GraphRag输出JSON稳定很多。

4. 常见问题与排查技巧实录

4.1 “GraphRag太重了”：索引慢、Token烧钱的根本原因和解法

热词里的“graphrag 太重”，确实是所有上手用户的第一反应。我分析下来，重的本质不在代码，而在它调用了大量LLM请求。实体抽取、关系抽取、社区摘要、全局检索，每一层都在吃Token。一个问题4 to 5次LLM调用，整体成本自然高。

应对策略我整理成四条，从最省钱到最激进排列：

第一，控制源数据体量。一个景区1000字跟3000字，抽取Token消耗差别明显。景区介绍文本控制在1500字左右，信息密度够用，成本最少可降低40%。

第二，调低max_gleaning。这个参数和max_tokens直接相关，从2降到0能立省一轮纠错消耗。

第三，选用便宜模型跑索引。实测gpt-4o-mini做景区实体抽取，质量够用。只有社区摘要环节需要更强的总结能力，可以在settings.yaml中单独指定。

第四，如果能接受一定噪声，可以把chunk size调大到1500，减少分块数量，也就是减少总的LLM调用次数。

从实测来看，我最后把整套索引运行成本压到了每100篇文档约3到5美元。GraphRag不再是一个“有钱才玩得起”的框架。

4.2 建立索引前一定要处理好的编码、路径和版本问题

有几个边角问题会让人排查很久，列表记录下来：

我额外踩过一个坑：Windows路径下反斜杠导致input目录识别失败，解决办法是--root参数用正斜杠或相对路径，比如--root ./scenic_graphrag。

4.3 查询结果泛泛而谈、不够具体，问题多半在提示词和chunk

如果你发现GraphRag返回的推荐内容读起来像“杭州有很多著名景点值得一逛”这类废话，基本可以断定是社区摘要粒度不够，或者实体抽取不到位。

这里给三条排查思路。

优先检查实体抽取效果：打开output里的parquet文件，用pandas直接看抽出来了哪些实体。如果“断桥残雪”这类核心景点实体都没有，说明源文档中该景区相关描述太少，或chunk把描述切散了，调整chunk size和overlap。

其次看社区摘要：如果实体有了但摘要还是空泛，通常需要修改entity_extraction或community_report的提示词，让模型在摘要中显式列出覆盖的实体名和相互关系。

最后看查询方式：如果用的是global，样本输出本来就偏聚合，推荐结果一般不适合直接做景点列表；换个local查询往往能命中具体实体。

4.4 输出不稳定、同样的查询结果飘忽不定

GraphRag的查询链路里存在大量LLM采样，稳定性本身有限。我实测同一个问题在不同跑批中推荐结果可能有20%左右的浮动，这个在接受范围内。但如果浮动过大，优先排查社区摘要是否有明显错误，再看是不是提示词缺少约束。

想要提升稳定性，可以在提示词中明确要求“输出时以景点名称列表为骨架，每个景点给出不超过50字的推荐理由”，并限定输出格式。GraphRag支持自定义prompts目录下的提示词，你可以把默认提示词复制出来改成自己的版本，挂到settings.yaml的对应配置项里。这个方法比改代码成本低得多，效果立竿见影。

5. 这套系统的扩展空间与个人实践体会

一个垂直领域GraphRag项目的价值，并不仅仅在于推荐结果本身，更在于全流程里沉淀下来的知识资产。景区推荐只是个载体，同样的流程迁移到餐饮推荐、旅行路线规划、甚至企业内部的文档问答，底层逻辑完全一样。

我在做完这个项目后，后续扩展其实是朝两个方向走的：一是把图谱结果落到可视化面板上，让运营人员能看到整个景区的实体关系网络，相当于把推荐系统改成了“景区知识管理平台”；二是接入实时数据（如天气、客流、实时票价），把图谱从静态知识库升级为动态决策引擎。

最后分享一个体感很强的经验：GraphRag的坑大多不在框架本身，而在对“LLM能力边界”的理解。实体抽取质量决定了推荐质量，社区摘要质量决定了回答逻辑，提示词设计决定了输出形式。不要一开始就追求大而全的图谱，先把三个节点的数据跑通，再逐步扩大数据规模，这样排障时心里才有谱。

本文还有配套的精品资源，点击获取