内容
<!-- mcp-name: io.github.ralforion/orionbelt-chat -->
<p align="center">
<img src="https://raw.githubusercontent.com/ralforion/orionbelt-chat/main/assets/ORIONBELT_Logo.png" alt="OrionBelt Logo" width="400">
</p>
<h1 align="center">OrionBelt 聊天</h1>
<p align="center"><strong>适用于OrionBelt Analytics 和 Semantic Layer 的AI驱动聊天界面</strong></p>
[](https://github.com/ralforion/orionbelt-chat)
[](https://www.python.org/downloads/)
[](https://github.com/ralforion/orionbelt-chat/blob/main/LICENSE)
[](https://chainlit.io)
[](https://ai.pydantic.dev)
[](https://openrouter.ai)
[](https://github.com/ml-explore/mlx)
[](https://ollama.com)
一个生产就绪的聊天应用程序，连接到OrionBelt Analytics 和 OrionBelt Semantic Layer MCP服务器，提供用于数据库分析、语义建模和交互式数据可视化的对话界面。 使用Chainlit和Pydantic AI构建，支持多个LLM提供商（云和本地）。
> **更好的一起：** 与 [**OrionBelt Analytics**](https://github.com/ralfbecher/orionbelt-analytics) 和 [**OrionBelt Semantic Layer**](https://github.com/ralfbecher/orionbelt-semantic-layer) 无缝合作。 同时连接到两个MCP服务器，进行模式感知本体生成、语义建模、保证正确的SQL编译和交互式图表渲染。
<p align="center">
<img src="https://raw.githubusercontent.com/ralforion/orionbelt-chat/main/assets/OrionBelt_Chat_1_Start.jpg" alt="OrionBelt Chat — 启动并连接MCP服务器" width="800">
</p>
<p align="center"><em>启动 — 连接的MCP服务器、提供商和模型选择</em></p>
<p align="center">
<img src="https://raw.githubusercontent.com/ralforion/orionbelt-chat/main/assets/OrionBelt_Chat_2_Ontology.jpg" alt="OrionBelt Chat — 本体生成管道，带有文件下载" width="800">
</p>
<p align="center"><em>完整管道 — 模式分析、本体生成、语义丰富和文件下载</em></p>
<p align="center">
<img src="https://raw.githubusercontent.com/ralforion/orionbelt-chat/main/assets/OrionBelt_Chat_3_Charts.jpg" alt="OrionBelt Chat — 交互式Plotly图表" width="800">
</p>
<p align="center"><em>交互式图表 — 热力图、线图和分组条形图，通过Plotly.js原生渲染</em></p>
## 主要功能
### 多提供商LLM支持
- **OpenRouter** - 通过单个API访问300+模型（推荐用于生产）
- **MLX** - 使用mlx-openai-server在Apple Silicon上进行本地推理
- **Ollama** - 跨平台本地推理，设置简单
- **Anthropic** - 直接API访问（绕过OpenRouter）
- **OpenAI** - 直接API访问（绕过OpenRouter）
### MCP集成
- **双MCP服务器支持** - 同时连接到Analytics和Semantic Layer
- **优雅降级** - 一个无法访问的服务器不会阻止应用程序；代理启动时使用可用的服务器
- **自动重新连接** - 检测MCP会话丢失并自动重新连接
- **工具调用弹性** - 重试失败的工具调用最多3次；在错误时保留对话上下文
- **灵活传输** - Stdio（本地子进程）或Streamable HTTP（远程）每服务器
- **MCP采样（带有工具）** - 服务器可以将LLM调用委托回聊天客户端，通过`sampling/createMessage`。 客户端宣传`sampling.tools`子能力，以便服务器可以包含工具定义； 采样请求由环境配置的默认模型（`DEFAULT_PROVIDER` +匹配的`*_DEFAULT_MODEL`）处理
- **工具可见性** - 可折叠的步骤显示工具调用及其参数和结果
- **多轮上下文** - 使用Pydantic AI进行完整的对话历史记录管理
### 交互式图表
- **原生Plotly渲染** - 图表通过Chainlit的捆绑Plotly.js内联渲染（不需要Python plotly包）
- **FastMCP Apps集成** - 从`ui://`资源URI返回的MCP工具中获取图表数据
- **多种图表类型** - 条形图、线图、散点图、热力图，自动检测
- **多种提取策略** - 处理Plotly图形字典、`Plotly.newPlot()`在HTML中和裸轨迹数组
### Mermaid图表
- **客户端渲染** - Mermaid.js从CDN加载，在内联渲染`erDiagram`、`flowchart`、`sequenceDiagram`等图表类型
- **自动检测** - MCP工具结果中的Mermaid语法自动显示为渲染的图表
- **主题感知** - 在浅色和深色模式之间切换时，图表会重新渲染
### 文件下载
- **自动检测** - 在工具结果和LLM响应代码块中识别可下载内容
- **支持的格式** - Turtle/RDF（.ttl）、JSON、CSV、SQL、SPARQL、YAML、XML
- **智能提取** - 处理字典形状的工具返回（例如`{'success': True, 'content': '@prefix ...'}`）
- **内联附件** - 下载按钮直接出现在响应消息中
### 实时流媒体
- **逐token流媒体** - 随着模型生成，响应平滑渲染
- **思考指示器** - 模型处理前响应视觉旋转器
- **工具调用跟踪** - 每个MCP工具调用的视觉反馈，正确匹配结果
- **停止生成** - 点击停止按钮或按 **Escape** 取消
- **错误处理** - 带有清晰错误消息的优雅故障
### Chainlit UI
- **设置面板** - 飞行中切换提供商和模型；头部实时更新
- **自定义模型输入** - 使用特定版本覆盖默认模型
- **可自定义系统** - 编辑`system_prompt.md`或设置`SYSTEM_PROMPT_FILE`环境变量
- **消息召回** - 在输入中按 **Arrow Up/Down** 导航消息历史
- **响应式设计** - 在桌面和移动浏览器上运行
## 快速入门
### 先决条件
- **Python 3.11+** （推荐3.13）
- **uv** 包管理器（[安装](https://github.com/astral-sh/uv)）
- **OrionBelt Analytics** 和 **Semantic Layer** 仓库克隆到此仓库旁边
### 安装
```bash
# 克隆仓库
cd orionbelt-chat
# 安装依赖
uv sync
# 复制环境模板
cp .env.example .env
# 编辑.env并添加您的API密钥
```
### 配置
编辑 `.env` 并配置您的LLM提供商：
**选项1：OpenRouter（推荐用于云）**
```bash
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_DEFAULT_MODEL=anthropic/claude-sonnet-4-5
DEFAULT_PROVIDER=openrouter
```
**选项2：Anthropic直接**
```bash
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_DEFAULT_MODEL=claude-sonnet-4-6 # 或 claude-opus-4-6
DEFAULT_PROVIDER=anthropic
```
**选项3：OpenAI直接**
```bash
OPENAI_API_KEY=sk-...
OPENAI_DEFAULT_MODEL=gpt-4o
DEFAULT_PROVIDER=openai
```
**选项4：MLX本地（Apple Silicon）**
```bash
# 首先启动mlx-openai-server：
mlx-openai-server launch \
--model-path mlx-community/Qwen2.5-14B-Instruct-4bit \
--model-type lm \
--enable-auto-tool-choice \
--port 8000
MLX_DEFAULT_MODEL=mlx-community/Qwen2.5-14B-Instruct-4bit
DEFAULT_PROVIDER=mlx
```
**选项5：Ollama本地（跨平台）**
```bash
# 首先启动Ollama：ollama serve
OLLAMA_DEFAULT_MODEL=qwen2.5:14b
DEFAULT_PROVIDER=ollama
```
**MCP服务器路径：**
```bash
# 每个都可以是本地目录（stdio）或HTTP（S）URL（Streamable HTTP）：
ANALYTICS_SERVER_DIR=../orionbelt-analytics
SEMANTIC_LAYER_SERVER_DIR=../orionbelt-semantic-layer-mcp
# 远程示例：ANALYTICS_SERVER_DIR=https://analytics.example.com/mcp
```
**系统提示（可选）：**
```bash
# 覆盖默认系统提示文件（默认为system_prompt.md）
# SYSTEM_PROMPT_FILE=~/my_custom_prompt.md
```
### 运行
```bash
uv run chainlit run app.py --watch
```
在浏览器中打开 **http://localhost:8080**。
## 使用示例
**连接到数据库：**
```
连接到localhost上的PostgreSQL数据库
```
**模式分析：**
```
分析模式并显示所有具有关系的表
```
**查询图表：**
```
显示按产品类别划分的收入的条形图
```
**下载本体：**
```
生成本体并将其下载为Turtle
```
**探索语义模型：**
```
语义层中有哪些可用的OBML模型？
```
**生成OBML模型：**
```
为客户分析创建具有收入、订单数量和平均订单价值指标的OBML模型
```
## 架构
<p align="center">
<img src="https://raw.githubusercontent.com/ralforion/orionbelt-chat/main/assets/architecture.png" alt="OrionBelt Chat Architecture" width="800">
</p>
```
┌──────────────────────────────────────────────────────────────┐
│ OrionBelt Chat (Chainlit + Pydantic AI) │
│ │
│ ┌──────────┐ ┌──────────────────────────────────┐ │
│ │ 聊天界面 │ │ Pydantic AI 代理 + MCP 客户端 │ │
│ │ │────────>│ - 多轮上下文 │ │
│ │ Chainlit │ │ - 事件流媒体 │ │
│ │ 2.10+ │ │ - 工具编排 │ │
│ └──────────┘ └──────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│ │
│ ├──> orionbelt-analytics (MCP stdio 或 HTTP)
│ │ - 模式分析
│ │ - 本体生成和下载
│ │ - SQL执行
│ │ - 交互式Plotly图表
│ │
│ └──> orionbelt-semantic-layer (MCP stdio 或 HTTP)
│ - OBML模型管理
│ - 语义查询编译
│ - 保证正确的SQL
│
└──> LLM 提供商（OpenRouter/MLX/Ollama/Anthropic/OpenAI）
```
**关键组件：
- **Chainlit 2.10+** - 聊天界面框架，支持流媒体、步骤和设置
- **Pydantic AI 1.77+** - 代理框架，支持节点迭代（`agent.iter()`）
- **MCP传输** - Stdio（本地子进程）或Streamable HTTP（远程）每服务器
- **图表渲染器** - 来自FastMCP Apps `ui://`资源的原生Plotly渲染
- **Mermaid渲染器** - 客户端图表渲染通过Mermaid.js CDN
- **文件下载** - 自动检测可下载内容（TTL、JSON、CSV、SQL）
## 开发
```bash
# 安装开发依赖
uv sync --group dev
# 运行测试（当可用时）
uv run pytest
# 格式化代码
uv run ruff format
# 校验
uv run ruff check --fix
```
## 提供商详情
### OpenRouter
- **访问**：通过单个API访问300+模型
- **可靠性**：跨供应商的最佳工具调用支持
- **推荐模型**：
- `anthropic/claude-sonnet-4-5` - 速度和推理能力的最佳平衡
- `anthropic/claude-opus-4-5` - 最大智能
- `google/gemini-2.5-pro` - 快速且经济高效
- **设置**：在 [openrouter.ai](https://openrouter.ai) 获取API密钥
### Anthropic（直接）
- **访问**：直接API，无中间商
- **可用模型**：
- `claude-sonnet-4-6` - 快速，优秀的工具使用（默认）
- `claude-opus-4-6` - 最大智能
- `claude-haiku-4-5-20251001` - 最快，最低成本
- **设置**：在 [console.anthropic.com](https://console.anthropic.com) 获取API密钥
### OpenAI（直接）
- **访问**：直接API，无中间商
- **可用模型**：
- `gpt-4o` - 最佳平衡（默认）
- `gpt-4o-mini` - 快速且经济高效
- `o3-mini` - 推理模型
- **设置**：在 [platform.openai.com](https://platform.openai.com) 获取API密钥
### MLX（Apple Silicon）
- **平台**：配备Apple Silicon的Mac（M1/M2/M3/M4）
- **要求**：`mlx-openai-server`
- **推荐模型**：
- `mlx-community/Qwen2.5-14B-Instruct-4bit` - 优秀的工具使用
- `mlx-community/Qwen2.5-32B-Instruct-4bit` - 更好的推理（需要32GB+ RAM）
- **设置**：使用 `pip install mlx-openai-server` 安装
- **注意**：必须使用 `--enable-auto-tool-choice` 标志调用工具
### Ollama
- **平台**：跨平台（Mac/Linux/Windows）
- **易用性**：最简单的本地设置
- **推荐模型**：
- `qwen2.5:14b` - 良好的速度和准确性平衡
- `qwen2.5:32b` - 更好的推理（需要32GB+ RAM）
- **设置**：从 [ollama.com](https://ollama.com) 下载
- **注意**：内置的工具调用支持，使用instruct模型
## 故障排除
### MCP服务器无法连接
**症状：** 状态消息显示一个或多个服务器“连接失败”
应用程序即使某些服务器无法访问也会启动 - 它将显示哪些已连接，哪些失败。 如果会话在对话过程中中断，应用程序会自动重新连接。
**解决方案：
- 确保 `ANALYTICS_SERVER_DIR` 和 `SEMANTIC_LAYER_SERVER_DIR` 指向正确的路径
- 对于本地（stdio）：检查仓库是否安装了依赖项（`uv sync`）
- 对于远程（HTTP）：验证URL是否可达且服务器是否正在运行
- 验证MCP服务器可以独立启动（`uv run server.py`）
### 图表未渲染
**症状：** 图表在调用 `generate_chart` 工具调用后不显示
**解决方案：
- 验证 `orionbelt-analytics` 是否具有MCP Apps支持（v1.2.0+）
- 检查服务器日志中是否有 `Chart URI detected` 和 `Plotly JSON extracted` 消息
- 确保分析服务器返回 `ui://` 资源URI在工具结果中
- 验证资源内容是否包含可解析的Plotly图数据
### MLX 模型未调用工具
**症状：** 模型忽略工具并直接尝试回答
**解决方案：
- 确保 `--enable-auto-tool-choice` 标志在启动 `mlx-openai-server` 时设置
- 使用instruct-tuned模型（带有 `-Instruct` 后缀）
- 尝试不同的模型（Qwen2.5系列具有最佳工具支持）
- 检查 `mlx-openai-server` 日志是否有错误
### 流媒体停止或挂起
**症状：** 响应在生成过程中停止或“思考”指示器保持可见
**解决方案：
- 按 **Escape** 或点击停止按钮取消，然后重试
- 检查MCP服务器日志是否有错误
- 验证工具调用是否成功完成（在UI中展开步骤）
- 如果使用慢速本地模型，增加超时设置
- 检查服务器控制台的详细日志（每个节点转换都被记录）
## 许可证
在 **Business Source License 1.1（BSL 1.1）** 许可。
- **允许生产用于内部/个人使用**
- **商业嵌入/ SaaS 限制** - 联系 [licensing@ralforion.com](mailto:licensing@ralforion.com）
- **更改日期**：2030-04-05
- **更改许可证**：Apache 2.0
查看 [LICENSE](./LICENSE) 获取完整条款。
## 链接
### OrionBelt 平台
- [**OrionBelt Analytics**](https://github.com/ralfbecher/orionbelt-analytics） - MCP服务器用于数据库分析和本体生成
- [**OrionBelt Semantic Layer**](https://github.com/ralfbecher/orionbelt-semantic-layer） -** MCP服务器用于OBML模型和语义SQL编译
- [**OrionBelt Ontology Builder**](https://github.com/ralfbecher/orionbelt-ontology-builder) - 视觉本体编辑器（Streamlit应用）
### 框架
- [**Chainlit**](https://docs.chainlit.io) - 聊天界面框架
- [**Pydantic AI**](https://ai.pydantic.dev) - 具有MCP支持的代理框架
- [**Model Context Protocol**](https://modelcontextprotocol.io) - 工具集成标准
### LLM 提供商
- [**OpenRouter**](https://openrouter.ai) - 统一API，用于300+模型
- [**MLX**](https://github.com/ml-explore/mlx) - Apple Silicon推理
- [**Ollama**](https://ollama.com) - 本地LLM运行时
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器