多卡文档助手
英语 · 俄语 · 乌兹别克语
英语
代理RAG-多卡支付平台API的文档助理。通过网络聊天机器人(带语音输入)、电报机器人(文本+语音消息)、MCP服务器和适用于任何OpenAPI规范的MCP服务器生成器为开发人员提供服务。
建筑```text
┌──────────────┐
│ Web Chat │ localhost:8000
│ (text+voice) │
└──────┬───────┘
│
┌──────────────┐ ┌──────┴───────┐ ┌──────────────┐
│ Telegram ├───┤ FastAPI ├───┤ MCP Server │
│ (text+voice) │ │ │ │ (/mcp or │
│ poll/webhook│ │ /api/chat │ │ stdio) │
└──────────────┘ │ /api/stream │ └──────────────┘
│ /api/specs │
└──────┬───────┘
│
┌──────────────┼──────────────┐
│ │ │
┌──────┴──────┐ ┌─────┴─────┐ ┌──────┴──────┐
│ Whisper │ │ LlamaIndex│ │ MCP Server │
│ (audio │ │ Agent │ │ Generator │
│ transcribe) │ │(multi-step│ │ (codegen) │
└─────────────┘ │ ReAct) │ └─────────────┘
├───────────┤
│ 6 Tools: │
│ search_ │
│ get_ │
│ list_* │
│ by_tag │
└─────┬─────┘
│
┌───────────┴───────────┐
│ PostgreSQL + pgvector │
│ - document_embeddings│
│ - memory (per-session│
│ facts + vectors) │
│ - telegram_messages │
│ - indexed_files │
└───────────────────────┘
### 技术栈
- **框架**:fastapi(异步)
- **AI/RAG**:LlamaIdex函数代理(多步骤ReAct)+矢量库索引
- **LLM**:OpenAI(gpt-4o-mini默认,可配置)
- **语音到文本**:OpenAI耳语(耳语-1)
- **嵌入**:text-embedding-3-small(1536昏暗)
- **数据库**:带pgvector的PostgreSQL
- **主控程序**:FastMCP(嵌入式HTTP+独立stdio)
- **电报**:轮询(dev)/Webhook(prod)、文本+语音消息
- **配置**:python解耦(.env)
- **包管理器**:紫外线
### 先决条件
- Python 3.12+
- PostgreSQL与 pg向量 扩展
- 紫外线 包管理器
- OpenAI API密钥
- Telegram机器人令牌(来自 @植物学家)
### 快速开始```bash
git clone && cd multidocs
cp .env.example .env # edit with your credentials
make setup # install deps, create db, index docs
make run # start the server
打开 http://localhost:8000 对于网络聊天机器人来说。
Makefile命令```bash
make help # show all commands
make run # start the server
make run/debug # start with hot reload
make index # index docs into vector store
make mcp # run standalone MCP server (stdio)
make db/create # create database + pgvector
make db/psql # open psql session
make lint # run ruff linter
make format # format code
make typecheck # run mypy
make test # run tests
make audit # run all quality checks
make setup # full project setup
### 项目结构```text
.
├── main.py # FastAPI app, lifespan, middleware, MCP mount
├── Makefile # Dev/prod commands
├── .env.example # Environment template
├── docs/ # Source documentation files
├── static/
│ └── index.html # Web chat UI (text + voice)
├── generated/ # Auto-generated MCP servers (gitignored)
├── scripts/
│ ├── index.py # Document indexing CLI
│ └── mcp_server.py # Standalone MCP server (stdio)
├── tests/ # Test suite (47 tests)
└── app/
├── config.py # Settings via python-decouple
├── database.py # Async engine, session factory
├── models.py # SQLAlchemy models
├── agent/
│ ├── engine.py # LLM, embeddings, vector store, memory, agent factories
│ ├── tools.py # 6 RAG tools (search, get, list, by_tag)
│ └── prompts.py # ReAct system prompt, context templates
├── generator/
│ └── codegen.py # OpenAPI → standalone MCP server generator
├── indexing/
│ ├── parser.py # OpenAPI spec → Documents with metadata
│ ├── loader.py # Multi-format loader (md, json, yaml, pdf, docx, html, csv, txt)
│ └── pipeline.py # Indexing with checksum tracking
├── api/
│ ├── router.py # All API endpoints
│ ├── schemas.py # Pydantic request/response models
│ └── deps.py # AppState singleton
├── telegram/
│ ├── webhook.py # Polling + webhook modes, text + voice handling
│ ├── handlers.py # Message storage, ring buffer, context
│ ├── audio.py # Whisper voice transcription
│ └── formatter.py # Markdown → Telegram HTML
└── mcp/
└── server.py # FastMCP tools
API终点
| 方法 | 路径 | 身份验证 | 描述 |
|---|---|---|---|
| 得到 | / |
- | 网络聊天用户界面 |
| 得到 | /api/health |
- | 健康检查(DB+OpenAI状态) |
| 职位 | /api/chat |
- | 聊天(JSON请求/响应) |
| 职位 | /api/chat/stream |
- | 聊天(流式文本响应) |
| 职位 | /api/transcribe |
- | 音频→ 通过Whisper发送文本 |
| 职位 | /api/admin/reindex |
管理员 | 强制重新索引所有文档 |
| 职位 | /api/admin/specs |
管理员 | 上传OpenAPI规范→ 生成MCP服务器 |
| 得到 | /api/admin/specs |
管理员 | 列出生成的MCP服务器 |
| 删除 | /api/admin/specs/{name} |
管理员 | 删除生成的MCP服务器 |
| 职位 | /webhook/telegram |
Webhook秘密 | 电报Webhook接收器 |
| * | /mcp/* |
承载令牌 | MCP服务器(流式HTTP) |
聊天API```bash
Standard
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{"message": "How do I authenticate?", "session_id": "my-session"}'
Streaming
curl -X POST http://localhost:8000/api/chat/stream \
-H "Content-Type: application/json" \
-d '{"message": "How do I authenticate?", "session_id": "my-session"}'
Voice transcription
curl -X POST http://localhost:8000/api/transcribe \
-F "file=@recording.webm"
### 代理式检索增强生成
该代理使用6个工具的多步骤ReAct方法:
|工具|目的|
| ---- | ------- |
| `search_docs` |跨所有索引内容的广泛语义搜索|
| `search_endpoints` |API端点定义上的筛选搜索|
| `search_guides` |通过降价指南进行筛选搜索|
| `get_endpoint_details` |特定端点的完整JSON规范(路径+方法)|
| `list_endpoints` |列出所有端点,可选择按标签筛选|
| `search_by_tag` |查找类别中的所有端点(模糊标记匹配)|
代理为每个查询链接多个工具调用:发现端点→ 获取详细信息→ 交叉参考指南→ 用代码示例综合一个完整的答案。
### 语音输入
使用OpenAI Whisper转录语音消息(`whisper-1`):
- **网络聊天机器人**:单击麦克风按钮录制,再次单击停止。音频会自动转录和发送。
- **电报**:发送语音信息或音频文件。机器人会转录它并对文本做出响应。
### MCP服务器
两种模式:
**嵌入式** (使用FastAPI在 `/mcp`):```json
{
"mcpServers": {
"multicard": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp",
"headers": { "Authorization": "Bearer your-mcp-api-key" }
}
}
}
独立 (stdio,用于克劳德桌面/IDE):```json
{
"mcpServers": {
"multicard": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "scripts/mcp_server.py"],
"cwd": "/path/to/multidocs"
}
}
}
### MCP服务器生成器
上传任何OpenAPI规范,并自动生成一个独立的MCP服务器:```bash
# Upload spec
curl -X POST http://localhost:8000/api/admin/specs \
-H "Authorization: Bearer your-admin-key" \
-H "Content-Type: application/json" \
-d @my-api-spec.json
# List generated servers
curl http://localhost:8000/api/admin/specs \
-H "Authorization: Bearer your-admin-key"
# Delete a server
curl -X DELETE http://localhost:8000/api/admin/specs/my_api \
-H "Authorization: Bearer your-admin-key"
每个生成的服务器包括:
server.py--独立的FastMCP服务器,每个端点有一个工具spec.json--原始规格mcp_config.json--准备粘贴Claude Desktop/IDE的配置README.md--自动生成的文档
开发人员复制 mcp_config.json Claude/Cursor立即拥有API的结构化知识,用于生成准确的客户端代码。
添加文档
- 将文件放入
docs/目录。支持的格式:
| 格式 | 扩展名 |
|---|---|
| Markdown | .md |
| 纯文本 | .txt, .rst |
| OpenAPI | .json, .yaml, .yml |
.pdf |
|
| Word | .docx |
| HTML | .html, .htm |
| CSV | .csv |
- 运行索引:```bash
make index
索引使用SHA-256校验和,跳过未更改的文件。可以使用添加自定义格式 `@register_loader` 室内装饰师 loader.py.
### 电报机器人
集 `TELEGRAM_MODE` 在 `.env`:
- **`polling`** (默认)--Bot拉取更新。在本地工作,不需要公共URL。
- **`webhook`** --Telegram推送更新。需要 `TELEGRAM_WEBHOOK_URL` (公共HTTPS)和 `TELEGRAM_WEBHOOK_SECRET`.
机器人会对私聊中的所有消息做出响应。在群体中,它只在以下情况下做出反应 `@mentioned`。支持文本和语音消息。
### 记忆系统
每会话两层内存(按会话ID键控):
- **短期的**:FIFO聊天历史记录受以下限制 `MEMORY_TOKEN_LIMIT * 0.7`
- **长期**:FactExtractionMemoryBlock(自动总结关键事实)+VectorMemoryBlock(对过去对话的语义回忆)
会话ID: `tg_{chat_id}` 对于Telegram、用于web/API的客户端提供的UUID, `mcp_default` 对于MCP。
### 配置
所有设置通过 `.env` --看 .env.示例 查看完整列表。关键群体:
|变量|默认值|描述|
| -------- | ------- | ----------- |
| `OPENAI_API_KEY` |必需| OpenAI API密钥|
| `OPENAI_MODEL` |gpt-4o-mini|LLM型号|
| `DATABASE_*` |本地主机:5432| PostgreSQL连接|
| `TELEGRAM_MODE` |投票| `polling` 或 `webhook` |
| `MCP_API_KEY` |必需|/mcp的承载令牌|
| `ADMIN_API_KEY` |空|管理员端点的承载令牌|
| `AGENT_TIMEOUT` |120 |每次代理呼叫的最大秒数|
| `RATE_LIMIT_RPM` |30 |每次会话每分钟请求数|
| `MEMORY_TOKEN_LIMIT` |40000 |内存上下文窗口|
| `MEMORY_MAX_FACTS` |50 |每次会话提取的最大事实数|
### 生产部署
1. 集 `TELEGRAM_MODE=webhook` 使用公共HTTPS URL
1. 为设置强随机值 `MCP_API_KEY`, `ADMIN_API_KEY`, `TELEGRAM_WEBHOOK_SECRET`
1. 集 `ALLOWED_ORIGINS` 到您的前端域
1. 集 `APP_DEBUG=False`
1. 使用支持pgvector的托管PostgreSQL
1. 使用HTTPS在反向代理(nginx/caddy)后面运行
______________________________________________________________________
## 俄语
RAG代理是MultiCard API的文档助理。它通过Web聊天机器人(语音输入)、电报机器人(文本+语音消息)、MCP服务器和任何OpenAPI规范的MCP服务器生成器运行。
### 要求
- Python 3.12+
- PostgreSQL扩展 pg向量
- 批处理管理器 紫外线
- OpenAI API 关键
- 令牌 Telegram 机器人 @植物学家)
### 快速启动```bash
git clone && cd multidocs
cp .env.example .env # заполните своими ключами
make setup # установка зависимостей, создание БД, индексация
make run # запуск сервера
打开 http://localhost:8000 对于网络聊天机器人。
主要命令```bash
make help # показать все команды
make run # запустить сервер
make run/debug # запустить с hot reload
make index # индексировать документацию
make mcp # запустить MCP-сервер (stdio)
make db/create # создать базу данных + pgvector
make lint # запустить линтер
make test # запустить тесты
make audit # все проверки качества кода
### API结束点
方法→路径→授权→
得到 · `/` · 网上聊天
得到 · `/api/health` 状态检查(DB+OpenAI)
职位 · `/api/chat` (JSON查询/响应)
职位 · `/api/chat/stream` 回复(文本流)
职位 · `/api/transcribe` 通过Whisper的文本
职位 · `/api/admin/reindex` ÐadminÐÐÐÐÐÐÐÐÐÐÐ
职位 · `/api/admin/specs` ÐadminÐÐÐÐÐÐÐÐÐÐÐÐ
得到 · `/api/admin/specs` ►admin›生成的MCP服务器列表›
删除 · `/api/admin/specs/{name}` –admin→删除生成的MCP服务器›
职位 · `/webhook/telegram` ÐWebhook SecretÐÐÐÐÐÐÐÐÐÐÐ
* · `/mcp/*` ←Bearer Token→MCP服务器(Streamable HTTP)→
### 代理RAG
代理使用多步骤React方法和6个工具:
工具,目的。
| `search_docs` –对所有索引文档进行语义搜索›
| `search_endpoints` 搜索API Endpoint的定义
| `search_guides` 搜索Markdown指南
| `get_endpoint_details` –特定Endpoint的完整JSON规范→
| `list_endpoints` –按标签筛选的所有Endpoint列表→
| `search_by_tag` –搜索类别中的所有Endpoint(模糊匹配)。
代理链条调用多个工具:查找Endpoint→获取详细信息→对照手册→使用代码示例生成完整答案。
### 语音输入
语音信息通过OpenAI Whisper转录(`whisper-1`):
- **网络聊天机器人**:单击麦克风按钮录制,再次单击停止
- **电报**:发送语音消息或音频文件
### MCP服务器生成器
下载任何OpenAPI规范并获得完整的MCP服务器:```bash
curl -X POST http://localhost:8000/api/admin/specs \
-H "Authorization: Bearer your-admin-key" \
-H "Content-Type: application/json" \
-d @my-api-spec.json
生成: server.py, spec.json, mcp_config.json, README.md开发者复制 mcp_config.json 在MCP客户端中,Claude/Cursor立即获得有关该API的结构化知识。
增编
支持的格式: .md, .txt, .rst, .json, .yaml, .yml, .pdf, .docx, .html, .htm, .csv
- 将文件放在目录中
docs/ - 运行
make index
自定义格式是通过装饰器添加的 @register_loader 在 loader.py.
电报-бот
安装 TELEGRAM_MODE 在 .env:
polling(默认)-本地工作,没有公共URLwebhook制作需要公共HTTPS URL
机器人响应私人聊天中的所有消息。在小组中-仅在 @упоминании支持文本和语音消息。
制作
- 安装
TELEGRAM_MODE=webhook公共HTTPS URL - 指定可靠的密钥
MCP_API_KEY,ADMIN_API_KEY,TELEGRAM_WEBHOOK_SECRET - 请输入
ALLOWED_ORIGINS使用前端域 - 安装
APP_DEBUG=False - 使用支持PgVector的托管PostgreSQL
- 使用HTTPS运行反向代理(nginx/caddy)
乌兹别克语
多卡支付平台API文档的代理RAG助理。Web聊天机器人(带语音输入),Telegram机器人(文本+语音消息),MCP服务器以及任何OpenAPI规范的MCP服务器生成器都可以运行。
要求
- Python 3.12+
- pg向量 kengaytmasi bilan PostgreSQL
- 紫外线 墨西哥总统
- OpenAI API kaliti
- Telegram机器人代币(@植物学家 丹玲)
快速启动```bash
git clone && cd multidocs
cp .env.example .env # o'z kalitlaringizni kiriting
make setup # bog'liqliklarni o'rnatish, bazani yaratish, indekslash
make run # serverni ishga tushirish
Web聊天机器人 **http://localhost:8000** 奥庆先生。
### 基本命令```bash
make help # barcha buyruqlarni ko'rsatish
make run # serverni ishga tushirish
make run/debug # hot reload bilan ishga tushirish
make index # dokumentatsiyani indekslash
make mcp # MCP-serverni ishga tushirish (stdio)
make db/create # ma'lumotlar bazasini yaratish + pgvector
make lint # linterni ishga tushirish
make test # testlarni ishga tushirish
make audit # kod sifatining barcha tekshiruvlari
API 终端列表
方法 · 方法 · 验证 · 描述
得到 · / · Veb聊天机器人
得到 · /api/health · -Holat tekshiruvi(DB+OpenAI)
职位 · /api/chat · 聊天(JSON so'rov/javob)
职位 · /api/chat/stream · Chat (流式文本回复)
职位 · /api/transcribe · 音频→文本通过Whisper
职位 · /api/admin/reindex · 管理员 · 重新索引文档
职位 · /api/admin/specs · 管理员 · 下载OpenAPI → MCP服务器生成
得到 · /api/admin/specs · 管理员 · 已生成的MCP服务器列表
删除 · /api/admin/specs/{name} · 管理员 · 删除已生成的 MCP 服务器
职位 · /webhook/telegram · Webhook secret · Telegram webhook 接收器
* · /mcp/* · 承载令牌 · MCP服务器(流式HTTP)
阿根特利RAG
Agent 采用多阶段 ReAct 方法使用 6 种工具:
| search_docs 对所有索引内容进行语义搜索。
| search_endpoints 按 API 端点定义过滤的搜索
search_guides · Markdown应用程序过滤搜索
| get_endpoint_details 特定端点的完整JSON规范。
list_endpoints · 所有端点列表,按标签过滤
| search_by_tag 按类别查找所有终端。
代理为一个查询调用多个工具链:查找端点 → 获取详细信息 → 与手册进行比较 → 提供完整的代码示例。
语音输入
语音 消息 OpenAI Whisperwhisper-1)通过转录:
- Veb聊天机器人: 按麦克风键写入, 再按停止
- 电报发送语音消息或音频文件:
MCP 服务器生成器
下载任何OpenAPI规范并获取现成的MCP服务器:```bash
curl -X POST http://localhost:8000/api/admin/specs \
-H "Authorization: Bearer your-admin-key" \
-H "Content-Type: application/json" \
-d @my-api-spec.json
正在生成 : `server.py`, `spec.json`, `mcp_config.json`, `README.md`达斯图尔奇 `mcp_config.json` 将其复制到 MCP 客户端, Claude/Cursor 现在就有了对 API 的基础知识。
### 添加文档
支持的格式 : `.md`, `.txt`, `.rst`, `.json`, `.yaml`, `.yml`, `.pdf`, `.docx`, `.html`, `.htm`, `.csv`
1. 文件 `docs/` 放入资料夹
1. `make index` 启动
特殊格式 loader.py 大哥 `@register_loader` 通过装饰添加。
### 电报机器人
`.env` 文件 `TELEGRAM_MODE` 尼索兹朗:
- **`polling`** (标准) — 本地工作,不需要通用 URL
- **`webhook`** — 要制作, 需要一个通用的 HTTPS URL
该机器人在私人聊天中回复所有消息。只在群组中 `@eslatilganda` 回答。支持文本和语音消息。
### MCP服务器
**已安装** (FastAPI双蓝 `/mcp` 也适用于):```json
{
"mcpServers": {
"multicard": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp",
"headers": { "Authorization": "Bearer your-mcp-api-key" }
}
}
}
独立 (stdio,克劳德桌面/IDE乌春):json
{
"mcpServers": {
"multicard": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "scripts/mcp_server.py"],
"cwd": "/path/to/multidocs"
}
}
}
投入生产
TELEGRAM_MODE=webhook使用通用 HTTPS URL 设置MCP_API_KEY,ADMIN_API_KEY,TELEGRAM_WEBHOOK_SECRET设置强大的随机密钥ALLOWED_ORIGINS输入您的 ga 前端域名APP_DEBUG=FalseO'rnating- 使用 pgvector 支持的可管理 PostgreSQL
- 使用 HTTPS 反向代理 (nginx/caddy) 启动
