shreesha345/Rudra-One
GitHub: shreesha345/Rudra-One
RudraOne 是一个基于 SigNoz 深度可观测性的 AI 语音紧急调度系统，旨在解决实时紧急呼叫处理中的毫秒级延迟定位与端到端链路追踪问题。
Stars: 0 | Forks: 0
# RudraOne — 具备深度 SigNoz 可观测性的 AI 语音紧急调度系统
RudraOne 是一个实时、低延迟的语音紧急调度 AI agent。它旨在处理关键的 911 呼叫、解析事件报告、对紧急情况进行地理定位，并调度附近的机构。为了保证在生死攸关的场景中所需的毫秒级可靠性，整个应用深度集成了 **OpenTelemetry (OTel)**，将指标、分布式 trace 和相关日志导出到 **SigNoz**。
## 📺 项目演示
*(此处将附带一段视频演示，展示实时语音通话、实时调度地图以及 SigNoz 内部的关联 trace 诊断)*
## 🚨 问题陈述
紧急响应语音 agent 对延迟的要求极其严格。处于危机中的人无法等待反应迟钝的 AI。
RudraOne 运行着一个复杂的异步 pipeline：
1. **实时音频流**：浏览器 WebSockets 将音频流传输到后端。
2. **实时语音转写**：后端将分块音频流传输到 Deepgram (STT)。
3. **LLM 推理**：FastAPI 后端向兼容 OpenAI 的 LLM（例如 OpenAI、DeepSeek 或 Vultr）发送 prompt，以对呼叫进行分类、提取位置上下文并生成响应。
4. **语音合成**：通过 ElevenLabs (TTS) 将 LLM 响应转换为音频。
5. **数据库事务**：呼叫转写、位置和调度详情异步保存到 PostgreSQL。
如果通话卡顿或出现延迟，标准的 APM 设置无法隔离瓶颈。我们必须立即知道：是网络 socket 的问题？Deepgram 转写延迟？LLM 响应生成？ElevenLabs 语音合成？还是向 PostgreSQL 写入 SQL 过慢？
## 💡 解决方案：为什么选择 SigNoz？
为了解决这些延迟和可靠性挑战，我们选择了 **SigNoz** 作为统一的可观测性平台。
### 为什么 SigNoz 是最佳选择：
1. **开源且易于部署**：与需要复杂入驻流程、闭源 agent 和许可协议的专有 APM 供应商（Datadog、New Relic）不同，SigNoz 是完全开源的。使用 **SigNoz Foundry (`foundryctl`)**，我们可以使用单个声明式配置文件 (`casting.yaml`) 在几秒钟内在本地建立完整的 SigNoz 技术栈（ClickHouse 数据库、OpenTelemetry Collector、Query-Service 和前端）。
2. **AI 原生可观测性**：自定义遥测标签支持对现代 AI 原生应用进行监控。通过 trace LLM prompt、completion 使用情况、token 指标和活动模型属性，SigNoz 为我们 AI pipeline 的内部工作原理提供了完全的透明度。
3. **深度 APM 与自定义 AI Span**：SigNoz 对自定义 OpenTelemetry span 的原生支持，使我们能够在单个端到端的分布式 trace 中 trace LLM completion、TTS 音频生成以及浏览器用户点击。
4. **日志到 Trace 的关联**：通过将活动的 trace ID 直接嵌入到我们的后端 logger 中，SigNoz 将日志映射到其起源的 span。当呼叫失败时，我们可以点击 SigNoz Logs Explorer 中的错误日志，并立即跳转到确切的 span 火焰图，以检查数据库查询或 API payload。
5. **无供应商锁定**：完全基于 OpenTelemetry 标准构建。如果我们扩大规模，可以重新指向我们的遥测 exporter endpoint，而无需更改任何一行应用代码。
## 🛠️ 使用的可观测性功能
### 1. 分布式追踪与服务地图
* **React Frontend**：自动检测浏览器 HTTP 请求和用户点击，将 W3C 上下文头部（`traceparent`）传播到后端。
* **FastAPI 后端**：读取上下文头部以将浏览器操作与服务端路由关联，自动生成统一的 trace 火焰图并构建 **SigNoz Service Map**。
* **PostgreSQL 数据库**：自动检测每一个 ORM 引擎事件和原始驱动操作（`asyncpg`），在 trace 时间线中直接暴露慢查询。
### 2. 自定义 APM 与 AI Token 使用看板
我们构建了一个自定义的 V5 看板来监控整个调度 pipeline：
* **KPI 指标**：总请求数、错误数和平均后端执行延迟（毫秒）。
* **Token 跟踪**：随时间跟踪 **Prompt**、**Completion** 和 **消耗的 LLM 总 token 数**的数值图和折线图。
* **响应延迟**：实时跟踪每分钟请求持续时间的图表。
* **Top Endpoint 表**：显示最活跃的 FastAPI 路由、它们的平均延迟和错误率。
### 3. 日志浏览器与日志查询构建器
后端日志记录格式化为注入 OTel 上下文标签：`[otelTraceID=... otelSpanID=...]`。使用日志查询构建器，我们可以按 `serviceName = 'rudraone-backend'` 进行过滤，按日志级别进行查询，并检查相关的请求历史记录。
### 4. 异常分析
任何未处理的异常、数据库事务冲突或 API 配额（例如 ElevenLabs 配额限制或 Twilio API 超时）都会作为 span 事件被捕获，并在 SigNoz 的 **Exceptions** 选项卡中报告完整的 Python 堆栈跟踪。
## 🏗️ 技术深入剖析：架构流程
以下是紧急语音调度 pipeline 的端到端执行序列。它突出了用户和操作员交互如何通过网络和数据库层进行传播，以及 **SigNoz** 如何在每一步异步收集分布式 trace、自定义属性和相关日志：
```
sequenceDiagram
autonumber
actor Caller
participant Twilio
participant Frontend as Frontend Dispatcher
participant Backend as FastAPI Backend
participant DB as PostgreSQL Database
participant Deepgram as Deepgram (STT)
participant TTS as ElevenLabs/Sarvam (TTS)
participant Services as Emergency Services
participant SigNoz as SigNoz Observability
Caller->>Twilio: Dials emergency number
Twilio->>Backend: POST /twiml (Incoming Call Webhook)
Note over Backend: Starts OTel Span: "/twiml"
Backend-->>SigNoz: Async export HTTP ingress traces
Backend->>Twilio: TwiML Response (
标签：API集成, SigNoz, 人工智能, 可观测性, 实时音频流处理, 应急响应系统, 测试用例, 用户代理, 用户模式Hook绕过, 自动化攻击, 语音识别与合成, 请求拦截