使用说明

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 <your-repo-url> 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：使用应用内秘密页面（推荐）

启动应用程序（见下面的步骤5）。
在主屏幕上，单击 “机密（API密钥和令牌）”.
填写：
- OPENAI_API_KEY （密码字段）
- GITHUB_TOOLSETS （例如。 repos,pull_requests,issues)
- GITHUB_PERSONAL_ACCESS_TOKEN （密码字段）
点击 “保存到环境中”.
- 这将更新正在运行的进程环境，并写入/更新 .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

本文：

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

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

打开 model/prompt.py 并定位 BASE_SYSTEM_PROMPT.
使用以下命令修改或扩展它：
- 特定领域的指导（矩阵、内部堆栈、合规性等）。
- 风格规则（短答案与长答案、代码重等）。
- 工具使用偏好：
  - 何时呼叫RAG与直接应答。
  - 何时检查GitHub、RAG和Matrix HS工具。
（可选）维护多个变体：
- BASE_SYSTEM_PROMPT_DEVOPS
- BASE_SYSTEM_PROMPT_SUPPORT
- 等等然后选择在构建代理时使用哪一个。
更改后，重新启动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目录中运行此项目。

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

使用说明

Matrix聊天机器人

先决条件

快速启动

1.克隆存储库

2.创建并激活虚拟环境

3.安装依赖项

4.配置环境机密

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

选项B：编辑 .env 直接

5.运行应用程序

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

OPENAI_API_KEY

GITHUB_PERSONAL_ACCESS_TOKEN

GITHUB_TOOLSETS

应用程序页面

家

机密页面(render_secrets_page)

聊天页面(render_chat_page)

将网站嵌入Chroma(render_embedding_page)

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

聊天分析和性能(render_chat_analytics_page)

代理工具及其工作原理

1.核心法学硕士

2.矩阵RAG工具

3.GitHub MCP工具

4.矩阵HS MCP工具

底层技术

支持的型号

LLM模型

嵌入模型

数据存储位置和清理

聊天记录（SQLite）

Chroma DB

调整基础系统提示

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

其他注意事项和提示

相关 MCP

GitHub仓库解析工具

Qwen智能代理框架

本地RAG容器

AI记忆引擎

GitHub文档AI集成工具

语义搜索与推荐引擎

选项B：编辑 `.env` 直接

`OPENAI_API_KEY`

`GITHUB_PERSONAL_ACCESS_TOKEN`

`GITHUB_TOOLSETS`

机密页面(`render_secrets_page`)

聊天页面(`render_chat_page`)

将网站嵌入Chroma(`render_embedding_page`)

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

聊天分析和性能(`render_chat_analytics_page`)