BDC Doc RAG

Документация RAG MCP проекта bdc-assist

bdc_doc_mcp/config.py      env-driven embeddings/LLM/Chroma (replaces utils/__init__.set_emb_llm)
bdc_doc_mcp/ingest.py      .pkl/.md/.mdx/.txt/.pdf → embeddings → Chroma (replaces utils/chroma/utils.py)
bdc_doc_mcp/api.py         FastAPI: /health /search
bdc_doc_mcp/mcp_server.py  search_docs MCP tool for AI agents — self-contained, same search as the API
bdc_doc_mcp/preproc/       source-specific preprocessing pipeline
tests/                     self-checks + API / agent notebooks
data/                      preproc output (*.pkl), ingest input

Настройка

uv sync
cp .env.example .env    # then fill in keys/URLs

Исходные репозитории

Нужны только для предобработки (--sources all); API/MCP-сервер и загрузка существующих .pkl-файлов работают без них. Клонируйте рядом с этим репозиторием (или укажите переменные окружения на них):

git clone https://github.com/stagecc/interim-bdc-website ../interim-bdc-website   # BDC_WEBSITE_DIR
git clone https://github.com/stagecc/bdc-gitbook ../bdc-gitbook                   # BDC_GITBOOK_DIR

Модели

Для завершения используйте OpenAI API в Azure (gpt-4o-mini по умолчанию)

Для эмбеддингов используйте Ollama на Sterling (подключение через RENCI VPN)

kubectl -n ner port-forward svc/ollama 11434:11434

Или используйте локальную Ollama с моделью groonga/bge-m3-Q4_K_M-GGUF.

Related MCP server: okfy

Загрузка

Полная пересборка из всех источников (требуется клонирование двух исходных репозиториев — см. Настройка; записывает data/*.pkl, затем загружает их):

uv run python -m bdc_doc_mcp.preproc.pipeline --sources all --ingest --reset

Отдельные файлы или каталоги:

uv run python -m bdc_doc_mcp.ingest ./data/docs.pkl --doc-type docs   # BDC_Chatbot preproc .pkl
uv run python -m bdc_doc_mcp.ingest ../interim-bdc-website/src/pages --doc-type page --reset

Модели эмбеддингов не взаимозаменяемы в пределах коллекции — bge-m3 имеет 1024 измерения, text-embedding-3-small — 1536. Смена модели означает --reset и полную повторную загрузку.

API

uv run uvicorn bdc_doc_mcp.api:app --port 8000     # docs at /docs

mode — это embedding (по умолчанию; семантическое сходство, оценка = расстояние, чем меньше, тем лучше) или keyword (нечёткое сопоставление слов — игнорирует регистр/пунктуацию и допускает небольшие опечатки, поэтому picsure находит "PIC-SURE"; оценка = количество вхождений, чем больше, тем лучше — используйте для точных названий/аббревиатур). doc_type — это CSV типов для поиска (например, page,faq). Если не указано, ищутся только docs, page, faq и video — укажите fellow, update или event явно, чтобы искать по ним. date_from/date_to (ГГГГ-ММ-ДД, включительно) фильтруют по дате; только документы событий и обновлений имеют дату, поэтому фильтр по дате неявно сужает поиск до этих типов.

Сервис по замыслу только ищет; загрузка происходит офлайн через CLI (см. Загрузка), а ответ — задача вызывающей стороны: агент приносит свою LLM.

MCP

uv run python -m bdc_doc_mcp.mcp_server           # stdio
uv run python -m bdc_doc_mcp.mcp_server --http    # streamable HTTP, port MCP_PORT (default 8001)

Предоставляет один инструмент search_docs — тот же поиск, что и API, но напрямую запрашивает Chroma, поэтому API-сервис запускать не нужно. Требуется загруженный .chroma_db + эмбеддинги.

Stdio-клиенты (Claude Desktop/Code, Cursor) запускают сервер сами — зарегистрируйте его:

{"mcpServers": {"bdc-doc-mcp": {
  "command": "uv",
  "args": ["--directory", "/path/to/bdc-doc-mcp", "run", "python", "-m", "bdc_doc_mcp.mcp_server"]
}}}

Сетевые клиенты: вместо этого запустите --http и укажите им http://host:8001/mcp.

Смоук-тест: uv run python tests/test_mcp.py

Предобработка

bdc_doc_mcp/preproc/ — это конвейер BDC_Chatbot, портированный:

--no-contextualize пропускает вызов LLM для каждого чанка (гораздо быстрее, но слабее поиск). Пути к источникам берутся из BDC_WEBSITE_DIR / BDC_GITBOOK_DIR.

Тесты

uv run python tests/test_ingest.py                             # batching + chunk-id logic, no network
uv run python tests/test_keyword.py                            # keyword ranking, pure function, no DB or API
uv run python tests/test_mcp.py                                # starts the server over stdio and exercises its tools; needs .chroma_db + embeddings

Блокноты (каждый запускает API на свободном порту и завершает его в конце; обоим нужен загруженный .chroma_db):

• tests/api_test.ipynb — простое знакомство с API: /health, /search, фильтр doc_type. Требуются только локальные эмбеддинги.

• tests/agent_test.ipynb — агент с вызовом инструментов (deepagents): настроенная LLM получает search_docs как инструмент LangChain и решает, когда его вызывать. Также требуется доступность провайдера завершения.