multidocs (I33ym)

多卡文档助手

英语 | 俄语 | 乌兹别克语

______________________________________________________________________

英语

代理RAG-多卡支付平台API的文档助理。通过网络聊天机器人（带语音输入）、电报机器人（文本+语音消息）、MCP服务器和适用于任何OpenAPI规范的MCP服务器生成器为开发人员提供服务。

建筑

                    ┌──────────────┐
                    │   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机器人令牌（来自 @植物学家)

快速开始

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命令

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

项目结构

.
├── 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

# 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方法：

代理为每个查询链接多个工具调用：发现端点→ 获取详细信息→ 交叉参考指南→ 用代码示例综合一个完整的答案。

语音输入

使用OpenAI Whisper转录语音消息(whisper-1):

• 网络聊天机器人：单击麦克风按钮录制，再次单击停止。音频会自动转录和发送。
• 电报：发送语音信息或音频文件。机器人会转录它并对文本做出响应。

MCP服务器

两种模式：

嵌入式 （使用FastAPI在 /mcp):

{
  "mcpServers": {
    "multicard": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer your-mcp-api-key" }
    }
  }
}

独立 （stdio，用于克劳德桌面/IDE）：

{
  "mcpServers": {
    "multicard": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "scripts/mcp_server.py"],
      "cwd": "/path/to/multidocs"
    }
  }
}

MCP服务器生成器

上传任何OpenAPI规范，并自动生成一个独立的MCP服务器：

# 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的结构化知识，用于生成准确的客户端代码。

添加文档

1. 将文件放入 docs/ 目录。支持的格式：

1. 运行索引：

   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.示例 查看完整列表。关键群体：

生产部署

1. 集 TELEGRAM_MODE=webhook 使用公共HTTPS URL
2. 为设置强随机值 MCP_API_KEY, ADMIN_API_KEY, TELEGRAM_WEBHOOK_SECRET
3. 集 ALLOWED_ORIGINS 到您的前端域
4. 集 APP_DEBUG=False
5. 使用支持pgvector的托管PostgreSQL
6. 使用HTTPS在反向代理（nginx/caddy）后面运行

______________________________________________________________________

俄语

RAG代理是MultiCard API的文档助理。它通过Web聊天机器人（语音输入）、电报机器人（文本+语音消息）、MCP服务器和任何OpenAPI规范的MCP服务器生成器运行。

要求

• Python 3.12+
• PostgreSQL扩展 pg向量
• 批处理管理器 紫外线
• OpenAI API 关键
• 令牌 Telegram 机器人 @植物学家)

快速启动

git clone  && cd multidocs
cp .env.example .env   # заполните своими ключами
make setup             # установка зависимостей, создание БД, индексация
make run               # запуск сервера

打开 http://localhost:8000 对于网络聊天机器人。

主要命令

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服务器：

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/
2. 运行 make index

自定义格式是通过装饰器添加的 @register_loader 在 loader.py.

电报-бот

安装 TELEGRAM_MODE 在 .env:

• polling （默认）-本地工作，没有公共URL
• webhook 制作需要公共HTTPS URL

机器人响应私人聊天中的所有消息。在小组中-仅在 @упоминании支持文本和语音消息。

制作

1. 安装 TELEGRAM_MODE=webhook 公共HTTPS URL
2. 指定可靠的密钥 MCP_API_KEY, ADMIN_API_KEY, TELEGRAM_WEBHOOK_SECRET
3. 请输入 ALLOWED_ORIGINS 使用前端域
4. 安装 APP_DEBUG=False
5. 使用支持PgVector的托管PostgreSQL
6. 使用HTTPS运行反向代理（nginx/caddy）

______________________________________________________________________

乌兹别克语

多卡支付平台API文档的代理RAG助理。Web聊天机器人（带语音输入），Telegram机器人（文本+语音消息），MCP服务器以及任何OpenAPI规范的MCP服务器生成器都可以运行。

要求

• Python 3.12+
• pg向量 kengaytmasi bilan PostgreSQL
• 紫外线 墨西哥总统
• OpenAI API kaliti
• Telegram机器人代币(@植物学家 丹玲）

快速启动

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 奥庆先生。

基本命令

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 终端列表

阿根特利RAG

Agent 采用多阶段 ReAct 方法使用 6 种工具：

代理为一个查询调用多个工具链：查找端点 → 获取详细信息 → 与手册进行比较 → 提供完整的代码示例。

语音输入

语音 消息 OpenAI Whisperwhisper-1）通过转录：

• Veb聊天机器人: 按麦克风键写入， 再按停止
• 电报发送语音消息或音频文件：

MCP 服务器生成器

下载任何OpenAPI规范并获取现成的MCP服务器：

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/ 放入资料夹
2. make index 启动

特殊格式 loader.py 大哥 @register_loader 通过装饰添加。

电报机器人

.env 文件 TELEGRAM_MODE 尼索兹朗：

• polling （标准） — 本地工作，不需要通用 URL
• webhook — 要制作， 需要一个通用的 HTTPS URL

该机器人在私人聊天中回复所有消息。只在群组中 @eslatilganda 回答。支持文本和语音消息。

MCP服务器

已安装 （FastAPI双蓝 /mcp 也适用于）：

{
  "mcpServers": {
    "multicard": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer your-mcp-api-key" }
    }
  }
}

独立 （stdio，克劳德桌面/IDE乌春）：

{
  "mcpServers": {
    "multicard": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "scripts/mcp_server.py"],
      "cwd": "/path/to/multidocs"
    }
  }
}

投入生产

1. TELEGRAM_MODE=webhook 使用通用 HTTPS URL 设置
2. MCP_API_KEY, ADMIN_API_KEY, TELEGRAM_WEBHOOK_SECRET 设置强大的随机密钥
3. ALLOWED_ORIGINS 输入您的 ga 前端域名
4. APP_DEBUG=False O'rnating
5. 使用 pgvector 支持的可管理 PostgreSQL
6. 使用 HTTPS 反向代理 （nginx/caddy） 启动