Matrix-Chatbot

Matrix聊天机器人

基于Streamlit的Matrix/GitHub助手，配备基于Chroma的RAG、成本意识分析和基于MCP的工具。

聊天和嵌入工作流的用户指南可通过应用程序UI中的“帮助/指南”按钮获得。

______________________________________________________________________

先决条件

您需要在本地安装以下内容：

• Python 3.11+（推荐3.12）
• pip 和 venv
• Docker（用于GitHub MCP服务器和Matrix HS MCP工具）
• Git（克隆此存储库）
• 网络访问：

- OpenAI API - GitHub API（如果使用GitHub工具） - 您的Matrix主服务器（如果使用Matrix HS MCP工具）

______________________________________________________________________

快速启动

1.克隆存储库

git clone  matrix-chatbot
cd matrix-chatbot

2.创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# or on Windows:
# .venv\Scripts\activate

3.安装依赖项

pip install --upgrade pip
pip install -r requirements.txt

4.配置环境机密

您有两个选择：

选项A：使用应用内秘密页面（推荐）

1. 启动应用程序（见下面的步骤5）。

1. 在主屏幕上，单击 “机密（API密钥和令牌）”.

1. 填写：

- OPENAI_API_KEY （密码字段） - GITHUB_TOOLSETS （例如。 repos,pull_requests,issues) - GITHUB_PERSONAL_ACCESS_TOKEN （密码字段）

1. 点击 “保存到环境中”.

- 这将更新正在运行的进程环境，并写入/更新 .env 项目根目录下的文件。

选项B：编辑 .env 直接

创建一个 .env 项目根目录中的文件：

cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
GITHUB_TOOLSETS=repos,pull_requests,issues
GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...
EOF

申请内容如下：

• os.environ （真实环境）
• 然后回到 .env 对于任何缺失的值

______________________________________________________________________

5.运行应用程序

从项目根：

streamlit run app/main.py

然后打开终端中显示的URL（通常 http://localhost:8501).

______________________________________________________________________

所需的令牌以及为什么需要它们

OPENAI_API_KEY

使用人：

• 聊天响应的核心LLM代理
• RAG嵌入管道(text-embedding-* 型号）
• 任何其他基于OpenAI的工具/组件

如果没有此密钥：

• 聊天页面无法生成答案。
• 嵌入页面无法运行飞行前或嵌入。

GITHUB_PERSONAL_ACCESS_TOKEN

使用人：

• GitHub MCP服务器（在Docker中运行）访问GitHub只读API。

最小范围：

• 至少 repo 和 read:org 对于大多数现实世界的设置；您的确切范围要求取决于只读访问所需的存储库和操作。

功能上：

• 允许代理人 GitHub MCP工具 致：

- 检查存储库 - 读取问题并提取请求 - 读取版本和元数据

• 就这个应用程序而言，MCP层的所有访问都是只读的。

GITHUB_TOOLSETS

例子：

GITHUB_TOOLSETS=repos,pull_requests,issues

使用人：

• GitHub MCP服务器决定公开哪些工具集。

效果：

• 限制代理看到和可以调用的GitHub工具。
• 较小的设置限制了表面积和负载。

______________________________________________________________________

应用程序页面

Streamlit应用程序按以下方式路由 app/main.py.页数：

家

带有导航按钮的登录页面：

• 与Matrix机器人聊天
• 将网站嵌入Chroma
• 查看RAG统计数据和可视化
• 聊天分析和性能
• 秘密（API密钥和令牌）

机密页面(render_secrets_page)

• 从以下位置读取值：

- 环境变量 - .env 文件

• 允许您编辑：

- OPENAI_API_KEY - GITHUB_TOOLSETS - GITHUB_PERSONAL_ACCESS_TOKEN

• “保存到环境中”：

- 更新 os.environ 对于运行过程。 - 将组合映射保留回 .env （覆盖，评论丢失）。

聊天页面(render_chat_page)

• 多聊天界面，包括：

- SQLite支持的历史记录(data/chat_history.db) - 按聊天标题、重命名、删除 - 导出为JSON/CSV/PDF

• 设置侧栏：

- 色度路径和RAG系列选择 - 切换矩阵RAG工具 - 切换GitHub MCP工具 - 切换矩阵HS MCP工具 - LLM选型 - 代理流选项

• 代理人：

- 通过LangChain/LangGraph编排的语言模型+工具。 - 用于上下文的最后N条消息（窗口）。

• 成本显示：

- 每条辅助消息都显示一个标题，其中包含大致的LLM和工具成本 以美分和纳米美元为单位。

• “帮助/指南”按钮：

- 在所有聊天设置和代理如何工作的UI文档中。

将网站嵌入Chroma(render_embedding_page)

• 获取基本URL、分块参数和Chroma集合设置。

• 两种模式：

- 试运行（仅限飞行前）:

- 爬行+块而不写入Chroma。 - 显示文档计数、块计数、令牌估计和成本估计。

- 运行嵌入（写入Chroma）:

- 满管道：爬行→ 块→ 嵌入→ 写信给Chroma。 - 显示进度和最终矢量存储统计数据。

• “帮助/指南”按钮：

- 在UI文档中，介绍爬行、分块、限制和成本。

RAG统计数据和可视化(render_rag_stats_page)

• 用途 rag.rag_stats.RagStats 检查和可视化Chroma系列。

• 有助于：

- 验证集合大小和元数据 - 比较不同的嵌入运行

聊天分析和性能(render_chat_analytics_page)

• 从中提取消息度量 ChatStorage /SQLite。

• 全球业绩：

- 平均延迟 - p95潜伏期 - 错误率 - 延迟时间线

• 每次聊天细分：

- 随时间推移的延迟（仅限助理）

- 工具使用表

- 原始消息指标包括：

- 延迟 - 使用的工具 - 错误标志 - RAG/GitHub/Matrix MCP标志 - LLM模型 - 集合名称 - 成本相关领域（LLM和工具，美元/美分/纳米）

• 用于理解：

- 成本热点 - 工具使用模式 - 聊天的可靠性和性能

______________________________________________________________________

代理工具及其工作原理

该代理构建于 model/chat_agent.py 通过 build_agent。它使用LangChain/LangGraph工具并集成了多个工具组。

1.核心法学硕士

• 在聊天侧栏中选择OpenAI模型。

• 用于：

- 所有对话回复。 - 协调工具调用（决定何时调用RAG、GitHub、Matrix等）。

• 通过以下方式获取令牌和成本使用情况 usage_metadata / usage 关于消息。

2.矩阵RAG工具

启用方式：

• 设置有效的色度路径。
• 选择一个收藏。
• 选中侧栏中的“启用矩阵RAG工具”。

它的作用：

• 查询由嵌入管道创建的Chroma集合。
• 根据用户查询检索相关块（例如Matrix规范、文档）。
• 然后，代理将这些检索到的块融合为答案。

使用案例：

• 关于Matrix规格材料的深入问答。
• 关于您自己的文档的问题，如果您已经嵌入了它们。

笔记：

• 您可以嵌入多个集合（例如不同的块大小/模型）。
• 所选集合将被注入到系统提示中以实现透明度。

3.GitHub MCP工具

启用方式：

• 提供 GITHUB_PERSONAL_ACCESS_TOKEN 和 GITHUB_TOOLSETS.
• 在Docker中启动GitHub MCP服务器。
• 选中聊天侧栏中的“启用GitHub MCP只读工具”。

它们的作用（示例，取决于工具集）：

• repos：读取仓库元数据、树、文件。
• issues：列出/搜索GitHub问题。
• pull_requests：检查PR、它们的差异和元数据。

如何使用它们：

• 代理根据查询决定何时调用它们：

- “显示repo X中打开的bug。” - “上次发布有什么变化？”

• 工具调用记录在以下位置并可见：

- 代理推理扩展器（启用流媒体功能且关闭MCP时）。 - 聊天分析（工具使用计数）。

笔记：

• 启用GitHub MCP时：

- 流式更新已禁用（工具仅异步）。 - 您仍然可以看到使用的最终状态和工具名称。

4.矩阵HS MCP工具

启用方式：

• 为您的家庭服务器配备本地Matrix MCP服务器。
• 选中侧栏中的“启用Matrix HS MCP工具”。

他们做什么：

• 通过公共Matrix端点检查主服务器运行状况、版本和MSC功能。

• 适用于以下操作问题：

- “家庭服务员健康吗？” - “此主服务器宣传哪些MSC？”

集成：

• 当用户查询与基础设施/健康相关时，代理可以调用这些工具。

______________________________________________________________________

底层技术

• 溪流

- 前端UI和路由(app/main.py +页面模块）。

• 语言链/语言图

- 代理编排和工具调用。

• OpenAI API

- 聊天模型（LLM）和嵌入模型。

• 色度

- RAG集合的矢量存储。 - 默认路径： matrix_rag/chroma_db （可在UI中配置）。

• SQLite

- 聊天记录和分析数据通过 ChatStorage. - 默认文件： data/chat_history.db.

• GitHub MCP服务器

- 在Docker中运行，将GitHub作为一组MCP工具公开。

• Matrix HS MCP服务器

- Matrix主服务器工具的本地MCP服务器。

• ReportLab（可选）

- PDF导出聊天记录。

______________________________________________________________________

支持的型号

LLM模型

通过配置 rag.config.settings.llm_choices 和 llm_default.

开箱即用的成本逻辑特别认识到：

• gpt-4.1-nano
• gpt-4.1-mini
• gpt-4.1

你还添加了什么 llm_choices 仍然有效，但成本估算将回落到 DEFAULT_LLM_PRICING.

要添加明确的成本曲线，请执行以下操作：

• 更新 LLM_PRICING 在中映射 app/chat.py.

嵌入模型

由嵌入页面文本输入和默认值驱动：

• text-embedding-3-small （默认，便宜）
• text-embedding-3-large
• text-embedding-ada-002 （遗产）

这些产品的价格在 EMBED_MODEL_PRICES_USD_PER_1M 在 app/embedding.py. 如果您有以下情况，请更新此映射：

• 添加新的嵌入模型。
• 需要根据当前的OpenAI定价调整价格。

______________________________________________________________________

数据存储位置和清理

聊天记录（SQLite）

• 地点： data/chat_history.db

• 首次使用聊天页面时自动创建。

• 内容：

- 所有聊天记录、消息、元数据（延迟、工具、成本、标志）。

要删除所有聊天记录：

rm -f data/chat_history.db

该应用程序将在需要时重新创建一个空数据库。

Chroma DB

• 默认路径： matrix_rag/chroma_db

（在聊天侧栏“色度持久目录”和嵌入页面中设置。）

• 内容：

- 文档块和嵌入的集合。

要擦除所有Chroma数据：

rm -rf matrix_rag/chroma_db

要删除特定集合，请执行以下操作：

• 如果要删除，请使用您自己的Chroma管理脚本或RAG统计页面。
• 或者通过以下方式手动使用小脚本 chromadb.HttpClient 删除一个已命名的集合。

______________________________________________________________________

调整基础系统提示

核心系统提示存在于：

• model/prompt.py → BASE_SYSTEM_PROMPT

本文：

• 定义助理角色。
• 指定应如何使用工具。
• 描述预期的输出样式和约束。

如何根据您的用例进行调整

1. 打开 model/prompt.py 并定位 BASE_SYSTEM_PROMPT.

1. 使用以下命令修改或扩展它：

- 特定领域的指导（矩阵、内部堆栈、合规性等）。

- 风格规则（短答案与长答案、代码重等）。

- 工具使用偏好：

- 何时呼叫RAG与直接应答。 - 何时检查GitHub、RAG和Matrix HS工具。

1. （可选）维护多个变体：

- BASE_SYSTEM_PROMPT_DEVOPS - BASE_SYSTEM_PROMPT_SUPPORT - 等等 然后选择在构建代理时使用哪一个。

1. 更改后，重新启动Streamlit应用程序以确保加载更新的提示。

指导方针：

• 保留一个部分，列举所有工具以及如何/何时使用它们。

• 明确表示，当工具存在时，不要产生数据幻觉。

• 对于成本敏感的用例，指示模型：

- 与广泛的MCP勘探相比，更喜欢RAG。 - 避免不必要的工具调用。

______________________________________________________________________

其他注意事项和提示

• 如果GitHub MCP工具在聊天侧栏中显示错误：

- 检查Docker是否正在运行。 - 验证MCP服务器映像和配置。 - 检查一下 GITHUB_PERSONAL_ACCESS_TOKEN 和 GITHUB_TOOLSETS 设置。

• 如果Matrix HS MCP工具出现故障：

- 确认本地MCP服务器可访问。 - 验证主服务器基本URL和网络访问。

• 如果PDF导出失败：

- 安装 reportlab:

    pip install reportlab

• 性能方面：

- 使用 gpt-4.1-mini 以获得更便宜、更快的响应。 - 除非问题需要，否则使用更少的工具。

• 为了安全和隔离：

- 在专用的virtualenv和专用的Chroma目录中运行此项目。

这应该为您提供足够的细节，以便从头开始构建系统，管理机密和存储，并安全地为您自己的用例开发代理、工具和提示。