内容
# 农场助手 🌾
一个为印度农民打造的多语言、语音优先的咨询助手，完全基于 Sarvam AI 的技术栈构建。
[](https://kisan-mitra-voice-agent.onrender.com/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://sarvam.ai)
**🔗 实时演示：** https://kisan-mitra-voice-agent.onrender.com/
*(免费层 — 空闲后第一个请求需要 ~50s 来唤醒服务器)*
农民用自己的语言（如印地语、卡纳达语、泰米尔语等）提出问题，然后听到用同一种语言回答的问题。在后台，一个 Sarvam 管道处理整个循环：
```
Saaras v3（语音转文本）→ Sarvam-30B（推理 + 工具调用）→ Bulbul v3（文本转语音）
```
助手回答有关 **市场价格、天气、作物建议和政府计划** 的问题 — 通过工具调用来支撑每个答案，而不是猜测。天气和价格来自实时的公共 API；整个过程运行在 Sarvam 自己的模型上，因此印度语的语音、推理和语音合成保持在单个技术栈中。
## 功能
- **流式多轮聊天** — 一个 Streamlit 对话，回复按 token 流式传输（单次传递：工具内联解析，然后答案流式传输），语音自动播放。
- **完整的语音循环** — 语音输入，语音输出，农民使用自己的语言（7 种语言）。
- **基于工具调用的代理** — 一个显式、有界的 Sarvam-30B 循环，调用工具而不是编造价格或日期。
- **实时数据** — 实时天气（Open-Meteo）和实时市场价格（data.gov.in Agmarknet），当上游 API 宕机时，提供优雅的 `{error: ...}` 回退。
- **MCP 服务器** — 通过模型上下文协议向任何 MCP 客户端（Claude Desktop、Cursor、自定义代理）公开相同的四个工具。
- **评估框架** — 工具选择准确率、基于 groundtruth 的关键词、WER、延迟 p50/p95 和 **LLM-as-judge on sarvam-105b** 评估忠实度和口语友好度。
- **延迟作为一类指标** — 每个阶段都计时并在 UI 和评估报告中显示。
- **测试** — 39 个单元测试（网络和 LLM 完全模拟，关键功能免费），通过 ruff 进行 lint-clean。
## 先决条件
- Python 3.11 或更新版本
- 一个 **Sarvam AI API 密钥** — 在 [dashboard.sarvam.ai](https://dashboard.sarvam.ai) 免费层（语音、LLM 和 TTS 必需）
- *(可选)* 一个免费的 **data.gov.in API 密钥**，用于可靠的实时市场价格 — 应用程序自带一个公共示例密钥，虽有速率限制但仍可使用
## 安装
```bash
git clone https://github.com/MANOJ21K/kisan-mitra-voice-agent
cd kisan-mitra-voice-agent
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 然后添加你的 SARVAM_API_KEY
```
`.env` 密钥：
| 变量 | 必需 | 用途 |
|---|---|---|
| `SARVAM_API_KEY` | 是 | Saaras STT、Sarvam-30B、Bulbul TTS |
| `DATA_GOV_IN_API_KEY` | 否 | 实时市场价格（回退到速率限制的示例密钥） |
## 使用
### 运行语音应用程序
```bash
streamlit run streamlit_app.py
```
打开一个 **Streamlit 聊天**：单次多轮对话。回复 **按 token 流式传输**，**Bulbul 语音自动播放**，每个回合显示哪些工具触发以及每个阶段的延迟。
### 从 CLI 查询代理
```bash
python -m src.agent "Aaj Kolar mandi mein tamatar ka bhaav kya hai?"
```
```
问：Aaj Kolar mandi mein tamatar ka bhaav kya hai?
工具：['get_mandi_price']
答：Kolar mandi mein aaj tamatar ka modal bhaav 1200 rupaye prati quintal hai …
LLM 延迟：1768 毫秒，历时 2 回合
```
### 运行 MCP 服务器
```bash
python mcp_server/server.py # 标准输入输出传输
```
<details>
<summary>Claude Desktop 配置</summary>
```json
{
"mcpServers": {
"kisan-mitra": {
"command": "python",
"args": ["/absolute/path/to/kisan-mitra-voice-agent/mcp_server/server.py"]
}
}
}
```
</details>
### 运行评估框架
```bash
python eval/metrics.py # 关键功能自测试 WER + 百分位数学
python eval/run_eval.py # 工具 + 答案准确率 + 延迟（需要 SARVAM_API_KEY）
python eval/run_eval.py --judge --n 5 # 添加 sarvam-105b LLM-as-judge，前 5 个案例
python eval/run_eval.py --speak # 同时测量 TTS 延迟
```
```
Kisan Mitra 评估 — 12 个案例
工具准确率 ：11/12 (92%)
答案准确率 ：10/12 (83%)
评估者忠实度 ：平均 4.6/5 · 最低 3/5 (sarvam-105b)
评估者口语友好度：平均 4.8/5 · 最低 4/5
LLM 延迟 ：p50 620 毫秒 · p95 1180 毫秒 · 最大 1400 毫秒
```
*(说明 — 实际数字取决于您的密钥、地区和网络)*
## 数据源
| 工具 | 源 | 实时？ |
|---|---|---|
| `get_weather` | [Open-Meteo](https://open-meteo.com) 地理编码 + 预报（无密钥） | 实时 |
| `get_mandi_price` | [data.gov.in Agmarknet](https://data.gov.in) 每日市场价格馈送（免费密钥） | 实时 |
| `get_crop_advisory` | 精选农业最佳实践 | 参考 |
| `get_govt_scheme` | 精选计划事实（PM-Kisan、PMFBY、KCC、土壤健康） | 参考 |
语音和代理技术栈是实时的 Sarvam API。天气和市场价格是实时的第三方馈送 — 如果上游 API 无法访问，工具会返回一个明确的错误，助手会诚实地转述，而不会编造价格。作物建议和计划详情是精选的参考数据（稳定事实，在工具输出中标记为此类），而不是实时馈送。
## 测试
```bash
pip install ruff pytest
ruff check . # lint
python eval/metrics.py # 关键功能自测试
pytest -q # 39 个测试 — 网络和 LLM 模拟，无需 API 密钥
```
测试套件是无网络和无密钥的（模拟 API 和 LLM），因此可以在任何地方运行，无需凭证。
## 项目结构
```
kisan-mitra-voice-agent/
├── streamlit_app.py # Streamlit 语音聊天 — 应用程序入口点
├── src/
│ ├── config.py # 密钥、基本 URL、模型 ID、语言、数据源配置
│ ├── sarvam_client.py # Saaras STT · Bulbul TTS · Translate（每个返回延迟）
│ ├── tools.py # 4 个农民工具 + 模式 + 调度（单个注册表）
│ ├── agent.py # Sarvam-30B 工具调用循环（代理运行时）
│ └── pipeline.py # 音频 → STT → 代理 → TTS，每个阶段计时
├── mcp_server/server.py # MCP 服务器公开相同的工具
├── eval/
│ ├── metrics.py # WER + 延迟百分位（关键功能自测试）
│ ├── judge.py # LLM-as-judge on sarvam-105b
│ ├── run_eval.py # 黄金集运行器（--judge, --speak, --n）
│ └── golden_set.jsonl # 12 个标记测试案例（包括边缘案例）
├── tests/ # 39 个 pytest 测试 — 模拟网络 + LLM，无密钥
├── docs/architecture.md # 图表 + 设计原理
├── CLAUDE.md # 贡献者和 AI 代理的约定
├── Dockerfile
└── render.yaml # 一键 Render 部署蓝图
```
参见 [docs/architecture.md](docs/architecture.md) 以获取完整的图表和设计原理。
## 部署
实时演示在 Render 的免费层运行，从 `Dockerfile` 通过 `render.yaml` 部署。
### Render（一键蓝图）
1. 在 [Render](https://render.com)：**新建 +** → **蓝图** → 连接此仓库。
2. Render 读取 `render.yaml` 并配置 `kisan-mitra` Web 服务。
3. 在提示时设置 `SARVAM_API_KEY`（和可选的 `DATA_GOV_IN_API_KEY`）作为环境变量。
4. 应用 — Render 构建 Docker 镜像并提供应用程序。免费计划在 15 分钟空闲后休眠，并在下一个请求时冷启动（~50s）。
**保持唤醒（消除冷启动）：** 将一个免费的 [UptimeRobot](https://uptimerobot.com) HTTP 监视器指向 `https://<your-app>.onrender.com/_stcore/health`，每 5 分钟间隔一次，这样实例就不会空闲超时。这是免费层上最大的延迟改进。
### Docker
```bash
docker build -t kisan-mitra .
docker run -p 7860:7860 -e SARVAM_API_KEY=sk_your_key kisan-mitra
# 打开 http://localhost:7860
```
## 贡献
问题和拉取请求欢迎。 在打开 PR 之前，请运行 `ruff check .`、`pytest -q` 和 `python eval/metrics.py` — 这三个都必须通过。 贡献者和 AI 代理的约定在 [CLAUDE.md](CLAUDE.md) 中有文档。
## 致谢
- [Sarvam AI](https://sarvam.ai) — Saaras、Sarvam-30B、sarvam-105b 和 Bulbul 模型
- [Open-Meteo](https://open-meteo.com) — 免费天气预报
- [data.gov.in](https://data.gov.in) — Agmarknet 每日市场价格馈送
## 许可证
在 [MIT 许可证](LICENSE) 下发布。
