基于语义层的LLM Agent与图数据库集成实践：以电影推荐为例

1. 项目概述：用语义层为LLM与图数据库架起一座桥

最近在折腾大语言模型（LLM）与图数据库的集成，发现一个挺有意思的项目：llm-movieagent。这个项目本质上是一个“电影推荐智能体”，但它背后的设计思路，远比一个简单的聊天机器人要深刻。它解决了一个核心痛点：如何让一个只会“说人话”的LLM，去精准地操作一个高度结构化的图数据库（Neo4j）？

传统的做法可能是写一堆复杂的、硬编码的Cypher查询语句，然后让LLM去“猜”该用哪一条。这种方法不仅脆弱，而且难以维护。llm-movieagent引入了一个“语义层”（Semantic Layer）的概念，就像在LLM和数据库之间安排了一个精通业务和技术的“翻译官”。这个翻译官手里有一套定义好的“工具”（Tools），比如“查询电影信息”、“根据偏好推荐”、“记住用户喜好”。LLM只需要理解用户的自然语言意图，然后告诉翻译官“我想用哪个工具、参数是什么”，翻译官就能准确无误地转换成数据库操作。

我花了一周时间，从零部署、研究源码到扩展功能，把这个项目里里外外摸了一遍。整个过程下来，感觉这个架构非常优雅，特别适合那些需要将复杂业务逻辑（尤其是涉及多跳关系查询）暴露给自然语言交互的场景。接下来，我就把自己从环境搭建、原理剖析、核心工具实现到二次开发踩过的坑，毫无保留地分享给你。无论你是想快速搭建一个可用的智能体，还是想深入理解LLM Agent与知识图谱的结合，这篇内容都能给你提供一条清晰的路径。

2. 核心架构与设计思路拆解

2.1 为什么是“语义层”而不是“直接查询”？

在深入代码之前，我们必须先理解“语义层”在这个项目中的核心价值。想象一下，你直接让LLM生成Cypher查询语句来回答“给我推荐一部类似《盗梦空间》的科幻片”。LLM可能知道《盗梦空间》是电影，科幻是类型，但它需要精确知道：

1. 数据库中代表电影的节点标签是什么？（是Movie还是Film？）
2. 电影和类型之间的关系边叫什么？（是IN_GENRE还是BELONGS_TO？）
3. “类似”如何定义？是同导演、同演员，还是基于协同过滤的评分相似？
4. 生成的Cypher语法是否正确？能否避免注入攻击？

这个过程极易出错，且严重依赖LLM对特定数据库模式的“死记硬背”。而语义层将这些问题提前解决了。它向上对LLM暴露的是一组高度抽象、业务化的“功能”，比如get_movie_recommendations(criteria)；向下，它封装了具体的数据库模式、查询逻辑和优化策略。LLM的职责被简化为：理解用户意图 -> 选择正确的工具并填充参数。剩下的复杂转换工作，交给语义层这个可靠的中间件。

这种设计的优势非常明显：

• 稳定性高：工具（函数）的输入输出被严格定义，避免了LLM生成任意不可控查询的风险。
• 可维护性强：数据库模式变更时，你只需要修改语义层背后的工具实现，无需重新训练或提示LLM。
• 功能可解释：每个工具都有明确的描述，开发者和用户都能清楚知道这个智能体“能做什么，不能做什么”。
• 易于扩展：增加一个新功能（如“查找票房最高的电影”），就是增加一个新的工具定义和实现。

llm-movieagent项目就是这一理念的绝佳实践。它用neo4j-semantic-layer（一个基于LangChain的模板）实现了这个语义层，并通过OpenAI的Function Calling能力，让LLM学会了“调用”这些工具。

2.2 项目组件与数据流全景

这个项目采用Docker Compose编排，结构清晰，包含了三个核心服务：

1. Neo4j 服务：作为图数据库后端，存储所有的实体（电影、演员、用户）和关系（出演、评分、属于某类型）。这是智能体的“知识大脑”。
2. API 服务：这是项目的心脏。它基于neo4j-semantic-layer构建，主要干了三件事：
   • 封装工具：将针对Neo4j的查询逻辑（如信息检索、推荐、记忆）包装成一个个具有明确定义（函数名、描述、参数JSON Schema）的工具。
   • 集成LLM：接入OpenAI的LLM（如GPT-3.5/4），并通过LangChain的Agent框架，赋予LLM根据对话历史调用上述工具的能力。
   • 提供接口：暴露一个标准的HTTP API端点，供前端调用。
3. UI 服务：一个基于Streamlit构建的轻量级聊天界面。它调用后端的API，为用户提供一个直观的对话交互窗口。

完整的数据流是这样的：

• 用户在Streamlit界面输入：“我喜欢诺兰导演的电影，有推荐吗？”
• UI将这句话连同对话历史，发送给API服务。
• API服务中的LLM Agent分析这句话，识别出意图是“基于导演推荐电影”。它查看自己可用的工具列表，发现recommendation_tool可能适用，但需要更具体的参数。它可能会先调用information_tool查询“诺兰”导演的详细信息，获取其唯一标识（如tmdbId）。
• 然后，LLM Agent正式调用recommendation_tool，并传入参数director_id: "Christopher Nolan"或从信息工具中获取的ID。
• recommendation_tool内部执行一个预定义好的、优化过的Cypher查询，例如寻找诺兰导演的高评分电影，或者喜欢诺兰电影的用户还喜欢什么其他电影。
• 查询结果（一个电影列表）返回给LLM Agent。
• LLM Agent 将结构化的电影数据组织成一段流畅、友好的自然语言回复，例如：“克里斯托弗·诺兰执导了许多高分电影。我为您推荐以下几部：《盗梦空间》（评分8.8）、《星际穿越》（评分8.6）...”。
• 最终，这段回复通过API返回给Streamlit界面，呈现给用户。

这个流程中，LLM从未直接生成或接触Cypher语句，它只负责意图理解和语言组织，所有对数据库的“危险操作”都被安全地封装在工具内部。

3. 从零到一的部署与数据准备实操

3.1 环境配置与一键启动

项目最大的优点就是开箱即用。确保你的机器上安装了Docker和Docker Compose，接下来的步骤非常简单。

第一步：克隆项目并配置环境变量

git clone https://github.com/tomasonjo/llm-movieagent.git cd llm-movieagent

在项目根目录下，你会找到一个.env.example文件。复制它并创建你自己的.env文件：

cp .env.example .env

然后用你喜欢的编辑器打开.env文件，填入关键的配置信息：

OPENAI_API_KEY=sk-your-openai-api-key-here NEO4J_URI=bolt://neo4j:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=your_secure_password_here

关键提示1：关于Neo4j URI注意NEO4J_URI的值是bolt://neo4j:7687。这里的neo4j是Docker Compose网络中的服务名，而不是localhost。这是因为API容器和Neo4j容器在同一个Docker网络中，通过服务名相互访问。如果你未来想用本机已有的Neo4j，可以改为bolt://localhost:7687，但需要确保网络可达。

关键提示2：关于Neo4j密码默认的NEO4J_PASSWORD在docker-compose.yml中也有设置。为了保证一致性，建议将.env中的密码修改为与docker-compose.yml中NEO4J_AUTH环境变量设定的密码相同，或者反过来修改docker-compose.yml以读取.env文件。否则可能导致连接失败。最简单的做法是让两者保持一致，例如都设为password123（仅用于实验，生产环境务必使用强密码）。

第二步：一键启动所有服务配置好.env后，只需要一条命令：

docker-compose up -d

-d参数让服务在后台运行。Docker Compose会依次拉取镜像并启动三个容器：Neo4j、API和Streamlit UI。

第三步：验证服务状态启动完成后，运行docker-compose ps查看容器状态，确保所有服务都是Up。

• Neo4j：可以通过浏览器访问http://localhost:7474，使用配置的用户名密码登录，查看空的数据库。
• API：后端服务通常运行在http://localhost:8100（具体端口需查看docker-compose.yml或日志），健康检查端点可能是http://localhost:8100/health。
• UI：访问http://localhost:8501，你应该能看到一个简洁的Streamlit聊天界面。

如果页面无法打开，使用docker-compose logs -f service_name（例如docker-compose logs -f api）来查看具体容器的日志，排查错误。

3.2 注入电影数据：让智能体拥有“知识”

启动后的数据库是空的，智能体无话可说。我们需要向Neo4j中导入示例数据。项目提供了ingest.py脚本，它位于api/目录下。这个脚本会做几件重要的事：

1. 从网络下载或使用内置的MovieLens数据集。
2. 将电影、演员、用户、评分、类型等数据以节点和关系的形式导入Neo4j。
3. 创建全文索引：这是实现高效语义搜索的关键，后面会详细讲。

推荐在API容器内部运行脚本，因为容器内已配置好所有Python依赖和数据库连接环境。

# 首先，找到API容器的ID或名称 docker ps | grep llm-movieagent-api # 假设容器ID是 abc123，进入容器shell docker exec -it abc123 bash # 现在你已经在API容器内部了，运行数据注入脚本 cd /app # 通常工作目录在此 python ingest.py

运行过程会在终端打印日志，显示创建了多少节点、多少关系。完成后，你可以回到Neo4j浏览器 (http://localhost:7474)，运行MATCH (n) RETURN count(n)看看数据总量，或者跑一个简单的查询如MATCH (m:Movie {title: \"The Matrix\"}) RETURN m来验证数据已成功导入。

实操心得：理解数据模型在深入开发前，花点时间在Neo4j浏览器里探索一下数据模型非常有必要。执行CALL db.schema.visualization()可以查看图谱的概貌。你会看到类似这样的结构：

• 节点标签：Movie（电影）、Person（演员/导演）、User（用户）、Genre（类型）。
• 关系类型：ACTED_IN（出演）、DIRECTED（执导）、RATED（评分，包含rating属性）、IN_GENRE（属于某类型）。 理解这个结构，对于后续自定义工具或调试查询至关重要。例如，知道“用户评分”是通过(:User)-[r:RATED]->(:Movie)关系来存储的，你就能明白推荐算法是如何工作的。

4. 核心工具深度解析与自定义扩展

项目预定义了三个核心工具，它们构成了智能体能力的基石。我们不仅要会用，更要明白它们是怎么实现的，这样才能自己动手改造或新增工具。

4.1 信息工具：精准检索的基石

information_tool是智能体的“眼睛”。当用户提到“昆汀·塔伦蒂诺”、“《低俗小说》”时，智能体需要先用这个工具在数据库里找到对应的实体。

它的核心实现逻辑是什么？

1. 工具定义：在语义层中，这个工具被定义为一个函数，描述为“Retrieves data about movies or individuals”。它的输入参数可能是一个字符串query，代表用户提到的名称。
2. 背后查询：它并不是简单地用WHERE title = \"Pulp Fiction\"去匹配。为了提高召回率（尤其是应对拼写错误、简称），它利用了Neo4j的全文索引。ingest.py脚本创建了针对Movie节点title属性和Person节点name属性的全文索引。
3. 查询过程：工具接收到query后，会构造一个Cypher查询，使用CALL db.index.fulltext.queryNodes(...)来调用全文索引，进行模糊搜索。它会返回一个包含节点信息和相关度的列表。
4. 结果处理：工具可能只返回最匹配的Top N个结果，或者根据相关度阈值进行过滤。返回给LLM的是结构化的信息，比如电影的标题、上映年份、简介、主演列表等。

注意事项：全文索引 vs. 精确匹配为什么不用精确匹配？因为用户输入是自由的。“The Matrix” 用户可能输入 “matrix”。全文索引支持词干提取、模糊匹配，能更好地处理这种情况。在自定义工具时，如果你需要基于文本属性进行搜索，强烈建议先创建全文索引。创建索引的Cypher语句类似：

CREATE FULLTEXT INDEX entityNames IF NOT EXISTS FOR (n:Movie|Person) ON EACH [n.title, n.name]

这样，一个索引就能同时覆盖两种标签的多个属性。

4.2 推荐工具：个性化体验的核心

recommendation_tool是智能体的“大脑”。它根据用户的历史偏好（显式评分）或实时输入（如“我喜欢科幻片”），从图谱中挖掘出潜在喜欢的电影。

常见的推荐逻辑实现：项目可能实现了多种推荐策略，例如：

• 基于内容的推荐：“找和《盗梦空间》同一类型（科幻、惊悚）且评分高的其他电影。” 对应的Cypher可能通过IN_GENRE关系进行遍历。
• 协同过滤：“找到也给《盗梦空间》打了高分的用户，看看他们还喜欢什么电影。” 这通过(:User)-[:RATED]->(:Movie)关系模式进行多跳查询。
• 基于元路径的推荐：“推荐由《盗梦空间》的同一位演员（莱昂纳多·迪卡普里奥）主演的其他电影。” 这通过ACTED_IN关系进行查询。

在工具实现中，可能会设计多个输入参数，如movie_id,genre,director_name,limit等。LLM根据对话上下文，决定填充哪些参数。工具内部则根据提供的参数，选择并执行对应的推荐算法Cypher模板。

4.3 记忆工具：实现连续对话的关键

memory_tool是智能体的“笔记本”。这是实现真正个性化对话的杀手锏。没有它，每次对话都是独立的，智能体不会记得你上次说过你喜欢汤姆·汉克斯。

它是如何工作的？

1. 记忆存储：当用户表达明确的偏好，例如“我不喜欢恐怖片”或“汤姆·汉克斯是我最喜欢的演员”时，LLM识别出这是需要记忆的偏好信息，调用memory_tool。
2. 图谱存储：工具不会将这句话原文存到某个文本字段。而是将其结构化，在图谱中创建一个代表该用户的User节点（如果不存在），然后创建这个用户与相关实体（如Genre节点“Horror”、Person节点“Tom Hanks”）之间的关系。关系类型可能是DISLIKES_GENRE、LIKES_ACTOR，并可能带有strength（偏好强度）或context（来源语境）等属性。
3. 记忆读取：在后续对话中，当需要做推荐或回答问题时，相关的Cypher查询会主动“JOIN”或“过滤”掉与当前用户记忆相关的部分。例如，推荐电影时，查询末尾会加上AND NOT (user)-[:DISLIKES_GENRE]->(:Genre {name:\"Horror\"})来排除用户不喜欢的类型。

实操心得：记忆的粒度与挑战实现一个健壮的记忆系统颇具挑战。难点在于：

• 偏好提取：如何从用户随意的语句中（如“那个演阿甘的，他的片子都不错”）准确提取出实体（“Tom Hanks”）和情感极性（“喜欢”）？
• 冲突解决：用户今天说“喜欢科幻”，明天说“科幻片看腻了”，记忆该如何更新？是覆盖、衰减，还是记录时间戳并综合判断？
• 隐私考量：在真实产品中，存储用户个人偏好数据必须考虑隐私政策和数据安全。 在llm-movieagent的初始版本中，记忆工具可能相对简单。你可以将其作为一个起点，根据业务需求设计更复杂的记忆图谱模型。

4.4 如何添加一个自定义工具？

假设我们想增加一个box_office_tool，用于查询票房最高的电影。以下是具体步骤：

第一步：在语义层定义新工具你需要找到API服务中定义工具的地方（通常在api/packages/neo4j-semantic-layer/下的某个Python文件，如tools.py或agent.py）。仿照现有工具，添加一个新函数。

# 示例：在 tools.py 中添加 def get_top_box_office_movies(limit: int = 10) -> str: """ Retrieves the top movies by box office revenue. Args: limit (int): The number of top movies to return. Defaults to 10. Returns: str: A formatted string listing the top movies and their revenue. """ # 1. 构造Cypher查询。假设Movie节点有`revenue`属性。 query = """ MATCH (m:Movie) WHERE m.revenue IS NOT NULL RETURN m.title AS title, m.revenue AS revenue ORDER BY m.revenue DESC LIMIT $limit """ # 2. 执行查询（需要获取数据库会话） # 假设有一个全局的 `driver` 或会话对象 records, summary, keys = driver.execute_query(query, limit=limit) # 3. 格式化结果，使其对LLM友好 if not records: return "No box office data found." result_lines = [f"Top {limit} Movies by Box Office:"] for i, record in enumerate(records, 1): # 假设revenue以美元为单位，可以格式化一下 revenue_formatted = f"${record['revenue']:,.0f}" result_lines.append(f"{i}. {record['title']} - {revenue_formatted}") return "\n".join(result_lines) # 第二步：将这个函数注册到LangChain的工具列表中 from langchain.tools import Tool box_office_tool = Tool.from_function( func=get_top_box_office_movies, name="box_office_tool", description="Useful for when you need to find the highest-grossing movies. Input should be the number of movies you want to list (e.g., 5).", ) # 然后将这个tool添加到创建Agent时使用的tools列表里。

第二步：更新数据库（如果需要）如果现有的Movie节点没有revenue属性，你需要修改ingest.py脚本，在导入数据时加入票房信息，或者后续通过一个数据更新脚本补充。

第三步：重启服务并测试修改代码后，需要重建并重启API容器。

docker-compose up -d --build api

重启后，在Streamlit界面中尝试提问：“哪些电影票房最高？” 观察智能体是否能正确调用新工具并返回结果。

5. 深入原理：OpenAI Function Calling与LangChain Agent工作机制

5.1 OpenAI Function Calling 是如何被触发的？

很多人对“Function Calling”感到神秘，其实它的流程非常清晰。当你在LangChain中创建一个带有工具的Agent时，底层发生的事情是这样的：

1. 对话开始：用户输入“推荐一部诺兰的科幻片”。
2. 首次LLM调用：LangChain将系统提示词（“你是一个电影助手，可以使用以下工具...”）、对话历史、用户问题一起发送给OpenAI API。关键点：这次调用中，functions参数（或tools参数，取决于API版本）被附加上，其中包含了所有工具的定义（JSON Schema格式，包括名称、描述和参数结构）。
3. LLM的决策：OpenAI的模型不会执行任何代码，它只是分析输入和可用的工具列表，然后输出一个结构化的JSON响应。这个响应可能有两种情况：
   • 直接回答：如果问题很简单，无需工具（如“你好”），它会直接生成文本回复。
   • 调用工具：如果判断需要工具（如本例），它的回复会是一个特殊的格式，指明它想调用哪个工具（function_call或tool_calls），以及它根据用户问题推断出的工具参数（arguments）。例如，它可能输出：{"tool_calls": [{"id": "...", "type": "function", "function": {"name": "information_tool", "arguments": "{\"query\": \"Christopher Nolan\"}"}}]}。
4. 执行工具：LangChain Agent框架接收到这个响应，解析出要调用的工具名称和参数，然后在本地执行你预先注册好的Python函数information_tool(query="Christopher Nolan")。
5. 二次LLM调用：工具执行后返回结果（例如，诺兰的导演ID和电影列表）。LangChain将这个工具执行结果作为上一步的“函数调用”的返回，连同原始对话历史，再次发送给OpenAI LLM，让它“消化”这个结果并组织最终的自然语言回复。
6. 最终回复：LLM生成最终答案，返回给用户。

整个过程，LLM只负责“思考”（决定用什么工具、填什么参数）和“组织语言”，真正的“手脚”（数据查询、计算）都由本地代码完成。这既安全又高效。

5.2 LangChain Agent 的编排逻辑

LangChain提供了多种Agent类型（如OPENAI_FUNCTIONS,ZERO_SHOT_REACT_DESCRIPTION）。llm-movieagent项目很可能使用了OPENAI_FUNCTIONS或STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION这类与Function Calling深度集成的Agent。

它的核心是一个循环：

1. 观察：接收用户输入或上一步的工具输出。
2. 思考：调用LLM，LLM根据当前观察和可用工具，决定下一步动作（是回答，还是调用工具A/B/C）。
3. 行动：如果LLM决定调用工具，则框架执行对应的工具函数。
4. 再观察：将工具执行结果作为新的观察，进入下一轮循环，直到LLM决定给出最终答案。

这个循环使得Agent可以链式调用多个工具来完成复杂任务。例如，先调用information_tool确认“诺兰”，再调用recommendation_tool获取推荐，最后可能还会调用memory_tool记录用户对诺兰的偏好。

避坑指南：工具描述的重要性LLM选择工具的唯一依据就是你提供的工具名称和描述。因此，工具的描述（description）至关重要。它必须清晰、准确，最好包含使用场景和输入示例。糟糕的描述会导致LLM误用或不用该工具。例如，description=\"Finds movies\"就太模糊，而description=\"Useful for searching movies by title, director, or actor names. Input should be a search query string.\"则清晰得多。

6. 性能优化与生产级考量

6.1 查询性能优化：Cypher与索引

智能体的响应速度很大程度上取决于工具内Cypher查询的效率。对于图数据库，优化查询是不变的主题。

• 使用参数化查询：如之前示例中的$limit，永远不要用字符串拼接来构造Cypher，防止注入攻击并利用查询缓存。
• 创建合适的索引：除了全文索引，对于常用的属性查找（如Movie的releaseYear,Person的tmdbId），应创建常规的单属性索引CREATE INDEX ON :Movie(releaseYear)。对于经常遍历的关系，可以考虑关系类型索引。
• 分析查询计划：在Neo4j浏览器中，在查询前加上EXPLAIN或PROFILE来查看查询计划，识别全节点扫描等性能瓶颈。例如PROFILE MATCH (m:Movie)-[:IN_GENRE]->(g:Genre {name:\"Sci-Fi\"}) RETURN m.title LIMIT 20。
• 限制返回结果：在工具内部，务必对查询结果使用LIMIT。LLM不需要成千上万条记录，返回前10或20条最相关的即可。

6.2 智能体层面的优化

• 设置超时与重试：在LangChain Agent配置中，可以为工具调用设置超时，并实现简单的重试逻辑，避免因单个工具卡死导致整个会话僵住。
• 限制工具调用次数：通过max_iterations或max_execution_time参数限制Agent的思考-行动循环次数，防止在复杂或模糊问题上陷入无限循环。
• 优化系统提示词：系统提示词是Agent的“人格”和“行为准则”。清晰的指令能显著提升工具调用的准确率。例如，明确告诉它“如果你不确定用户指的是哪部电影，请先使用information_tool进行确认”。
• 使用更高效的模型：对于工具调用决策这个任务，gpt-3.5-turbo通常已经足够且成本更低。可以将最终组织回答的步骤也交给它，或者对于最终答案质量要求高的场景，使用gpt-4。

6.3 扩展性与部署建议

• 配置管理：将API密钥、数据库连接串、模型参数等全部通过环境变量或配置文件管理，便于不同环境（开发、测试、生产）的切换。
• 容器化：项目已经做到了，这是最佳实践。确保生产环境的Docker镜像使用特定版本标签，而非latest。
• API网关与认证：生产环境下的API服务不应直接暴露。应通过API网关（如Kong, APISIX）进行路由、限流、并添加API Key认证。
• 日志与监控：在工具函数和Agent调用关键点添加结构化日志（如JSON格式），便于使用ELK或Loki等工具进行聚合分析。监控API响应时间、错误率和Token消耗。
• 缓存策略：对于一些相对静态的查询结果（如票房Top10、经典电影信息），可以在工具层或API层引入缓存（如Redis），显著降低数据库压力和响应延迟。

7. 常见问题排查与调试技巧

在实际操作中，你肯定会遇到各种问题。这里记录一些我踩过的坑和解决方法。

问题1：启动Docker Compose后，API服务连接Neo4j失败。

• 现象：API容器日志不断报错Neo4jError: Could not perform discovery...或认证失败。
• 排查：
  1. 首先确认Neo4j容器是否健康运行：docker-compose logs neo4j。
  2. 检查.env文件中的NEO4J_URI。在Docker Compose网络内，应使用服务名neo4j而非localhost。
  3. 最常见原因：.env中的NEO4J_PASSWORD与docker-compose.yml中neo4j服务下NEO4J_AUTH环境变量设置的密码不一致。务必统一两者。
  4. 进入Neo4j容器，用cypher-shell测试连接：docker exec -it <neo4j_container> cypher-shell -u neo4j -p your_password。

问题2：智能体无法正确调用工具，总是直接回答或调用错误工具。

• 现象：问“诺兰的电影”，它直接编造一个列表，而不是去查询数据库。
• 排查：
  1. 检查工具描述：这是首要原因。确保工具的描述清晰无误，能让LLM理解何时使用它。
  2. 检查系统提示词：系统提示词是否明确指令Agent优先使用工具？可以尝试强化提示，如“你首先必须使用可用的工具来获取真实数据，严禁编造信息。”
  3. 启用详细日志：修改LangChain的日志级别，查看Agent的思考过程。在代码中添加import langchain; langchain.debug = True，可以在控制台看到LLM接收和发送的详细消息，观察它是如何做出决策的。
  4. 测试工具本身：绕过Agent，直接写一个脚本调用information_tool("Christopher Nolan")，看是否能返回正确结果，排除工具函数本身的bug。

问题3：查询结果准确率低，找不到电影。

• 现象：输入“Matrix”，工具返回了不相关的结果或空结果。
• 排查：
  1. 确认数据存在：直接在Neo4j浏览器中查询MATCH (m:Movie) WHERE toLower(m.title) CONTAINS 'matrix' RETURN m.title，确认数据已正确导入。
  2. 检查全文索引：确认全文索引已创建且包含正确标签和属性。在Neo4j浏览器中执行SHOW INDEXES查看索引详情。
  3. 分析工具查询逻辑：查看information_tool内部使用的Cypher语句。它可能设定了过高的相关度分数阈值，或者返回的结果数量限制太严格。尝试调整这些参数。

问题4：Streamlit界面无响应或报错。

• 现象：页面空白或显示“Connection Error”。
• 排查：
  1. 检查Streamlit容器日志：docker-compose logs -f ui。
  2. 确认UI配置的后端API地址是否正确。检查ui服务相关的环境变量或配置文件，确保它指向正确的api服务地址和端口（在Docker Compose网络内，通常是http://api:8100之类的形式）。
  3. 检查API服务是否健康：curl http://localhost:8100/health（端口以实际为准）。

这个项目是一个绝佳的起点，它清晰地展示了如何利用语义层和LLM Agent技术，将强大的图数据库能力以自然语言的方式释放出来。从我个人的实践来看，这套架构的潜力远不止于电影推荐。你可以将其迁移到任何需要复杂关系查询和个性化交互的领域，比如金融风控（查询关联企业）、医疗知识问答（查询病症与药品关系）、企业知识管理（查询文档与专家关系）等。核心在于设计好你的图谱数据模型，并围绕业务场景抽象出一套恰当的工具。剩下的，就交给LLM这位聪明的“协调员”吧。