Основы практической реализации

Автор: Артур Хайруллин | Дата публикации: 2025-08-14

Документация для модуля OCR обработки и векторизации

Эта документация описывает модуль для обработки PDF-документов, извлечения текста, фрагментации и векторизации данных с последующим сохранением в векторную базу данных. Модуль предназначен для подготовки данных для систем Retrieval-Augmented Generation (RAG).

Содержание

  1. Назначение
  2. Функциональность
  3. Требования
  4. Конфигурация
  5. Обработка данных
  6. Формат вывода
  7. Зависимости
  8. Примеры использования
  9. Ограничения

Назначение

Модуль OCR обработки и векторизации предназначен для автоматической обработки PDF-документов, извлечения текстовых данных, их фрагментации и преобразования в векторные представления для хранения в векторной базе данных (FAISS). Модуль поддерживает обработку как текстовых PDF, так и отсканированных документов с использованием OCR (Tesseract).

Функциональность

  1. Поиск PDF-документов:
  2. Извлечение текста:
  3. Обработка текста:
  4. Фрагментация текста:
  5. Векторизация:
  6. Сохранение данных:

Требования

Конфигурация

Модуль требует настройки следующих параметров:

Обработка данных

  1. Поиск файлов:
  2. Извлечение текста:
  3. Обработка текста:
  4. Фрагментация:
  5. Векторизация:
  6. Сохранение:

Формат вывода

{

  "metadata": {

    "550e8400-e29b-41d4-a716-446655440000": {

      "text": "Это пример текста из документа.",

      "fragment": 0,

      "file": "document.pdf",

      "folder": "folder1"

    },

    ...

  },

  "id_map": [

    "550e8400-e29b-41d4-a716-446655440000",

    ...

  ]

}

Зависимости

Модуль использует следующие Python-библиотеки:

Внешние инструменты

Примеры использования

Пример 1: Обработка PDF с текстовым слоем

Исходные данные:

Запуск:

bash

python sem_index_ocr.py

 

Вывод в консоль:

policy.pdf: есть текстовый слой — обрабатываем напрямую

Обработка завершена.

 

Результат:

{

  "metadata": {

    "550e8400-e29b-41d4-a716-446655440000": {

      "text": "Политика доступа: user001 имеет доступ к папкам /folder1 и /folder3.",

      "fragment": 0,

      "file": "policy.pdf",

      "folder": ""

    }

  },

  "id_map": ["550e8400-e29b-41d4-a716-446655440000"]

}

Пример 2: Обработка отсканированного PDF

Исходные данные:

Запуск:

bash

python sem_index_ocr.py

 

Вывод в консоль:

scanned.pdf: нет текстового слоя — выполняем OCR

Обработка завершена.

 

Результат:

{

  "metadata": {

    "123e4567-e89b-12d3-a456-426614174000": {

      "text": "Облачное хранилище обеспечивает масштабируемость.",

      "fragment": 0,

      "file": "scanned.pdf",

      "folder": ""

    }

  },

  "id_map": ["123e4567-e89b-12d3-a456-426614174000"]

}

Пример 3: Ошибка обработки

Исходные данные:

Запуск:

bash

python sem_index_ocr.py

 

Вывод в консоль:

Ошибка при обработке source/broken.pdf: Invalid PDF file

Обработка завершена.

 

Ограничения

Документация форматов взаимодействия с API RAG-системы

Эта документация описывает API для системы Retrieval-Augmented Generation (RAG), построенной с использованием векторной базы данных. API предоставляет два основных эндпоинта: прямой AI-чат и RAG-систему с учетом ролевой политики доступа.

Содержание

  1. Обзор
  2. Базовый URL
  3. Аутентификация
  4. Эндпоинты
  5. Ролевая политика доступа
  6. Обработка ошибок
  7. Зависимости
  8. Примеры использования
  9. Стартовая конфигурация
  10. Дополнительная конфигурация

Обзор

API обрабатывает запросы пользователя, используя гибридный подход в виде комбинации векторного поиска (FAISS и Sentence Transformers) и ключевого поиска (TF-IDF). Ответы генерируются с помощью внешнего OpenAI API. Система поддерживает ролевую политику доступа для ограничения данных по ролям пользователей.

Базовый URL

API доступен по адресу:

http://<host>:3000

 

По умолчанию приложение запускается на 0.0.0.0:3000, CORS сконфигурирован на доступ без ограничений. При необходимости интеграция виджета в веб приложения использующие SSL расположенных по адресам https://… во избежание блокировки данных, необходимо выпустить ssl сертификаты, сконфигурировать сервер и виджет для работы по https.

Аутентификация

API не использует аутентификацию. Фильтрация выдачи осуществляется через параметр role в запросе к эндпоинту /ask. Если параметр не указан, используется роль guest. Подробнее в разделе “Ролевая политика доступа”

Эндпоинты

POST /chat

Эндпоинт для тестового прямого взаимодействия с AI, отправляющий запросы в OpenAI API и возвращающий потоковый ответ.

Запрос

{

  "prompt": "строка"

}

Ответ

Пример

Запрос:

bash

curl -X POST http://localhost:3000/chat \

-H "Content-Type: application/json" \

-d '{"prompt": "Объясни, что такое блокчейн"}'

 

Ответ:

Блокчейн — это децентрализованная и распределенная цифровая база данных, которая хранит записи (транзакции) в виде блоков, связанных криптографически. Каждый блок содержит данные, хэш предыдущего блока и временную метку, что обеспечивает неизменность и прозрачность.

 

POST /ask

Основной эндпоинт RAG-системы, обрабатывающий запросы с использованием векторного и ключевого поиска, с учетом ролевой политики.

Запрос

{

  "prompt": "строка"

}

Ответ

в документах нет необходимой информации для ответа на этот вопрос, но ...

Получение контекста

[

  {

    "text": "строка",

    "fragment": "строка",

    "file": "строка",

    "folder": "строка",

    "search": "vect|key

 

  }

]

Пример

Запрос:

bash

curl -X POST http://localhost:3000/ask?role=user001 \

-H "Content-Type: application/json" \

-d '{"prompt": "Для чего нужна RAG система?"}'

 

Ответ:

RAG система обеспечивает AI генерацию дополненную поиском, в виде внешних извлеченных данных .

Источник: RAG.pdf

 

Если данных нет:

в документах нет необходимой информации для ответа на этот вопрос, но, основываясь на контексте, RAG система может применяться для формирования AI выдачи основанной на данных пользовательских документов.

 

POST /askchat

Дополнительный эндпоинт RAG-системы, обрабатывающий запросы с использованием векторного и ключевого поиска, в формате AI роли “Справочная система”.

POST /askassist

Дополнительный эндпоинт RAG-системы, обрабатывающий запросы с использованием векторного и ключевого поиска, в формате AI роли “Ассистент”.

Ролевая политика доступа

API использует ролевую политику для ограничения доступа к документам на основе роли пользователя, указанной в параметре role.

Определение ролей

Роли и доступные им папки определены в словаре role_folder_map:

python

role_folder_map = {

    "admin": ["*"],  # Доступ ко всем папкам

    "guest": ["*"],  # Доступ ко всем папкам

    "user001": ["folder1", "folder3"],

    "user002": ["folder5", "folder7"]

}

 

Роль по умолчанию

Если параметр role не указан, используется роль guest с доступом ко всем папкам (["*"]).

Обработка ошибок

Зависимости

API использует следующие Python-библиотеки:

Внешние сервисы

Предобученные модели

Файлы

Примеры использования

Пример 1: Прямой чат

Запрос:

bash

curl -X POST http://localhost:3000/chat \

-H "Content-Type: application/json" \

-d '{"prompt": "Объясни, что такое блокчейн"}'

 

. Ответ:

Блокчейн — это децентрализованная и распределенная цифровая база данных, которая хранит записи (транзакции) в виде блоков, связанных криптографически. Каждый блок содержит данные, хэш предыдущего блока и временную метку, что обеспечивает неизменность и прозрачность.

 

Пример 2: RAG-запрос с ролью

Запрос:

bash

curl -X POST http://localhost:3000/ask?role=user001 \

-H "Content-Type: application/json" \

-d '{"prompt": "Какие документы доступны user001?"}'

 

Ответ:

User001 имеет доступ к документам в папках /folder1 и /folder3.

Источник: role_policy.pdf

 

Пример 3: Запрос без релевантного контекста

Запрос:

bash

curl -X POST http://localhost:3000/ask?role=user002 \

-H "Content-Type: application/json" \

-d '{"prompt": "Как работает облачное хранилище?"}'

 

Ответ:

в документах нет необходимой информации для ответа на этот вопрос, но, основываясь на контексте, облачное хранилище позволяет хранить данные на удаленных серверах, обеспечивая доступ через интернет и высокую масштабируемость.

 

Стартовая конфигурация

Дополнительная конфигурация

Документация для модуля Telegram

Эта документация описывает модуль Telegram, предназначенный для обработки запросов из Telegram и генерации ответов с использованием системы RAG. Модуль интегрируется с Telegram-ботом и использует векторный и ключевой поиск для формирования релевантного контекста, который передаётся в модель AI для генерации ответа.

Содержание

  1. Назначение
  2. Функциональность
  3. Требования
  4. Конфигурация
  5. Обработка запросов
  6. Формат ответа
  7. Зависимости
  8. Примеры использования

Назначение

Модуль Telegram векторного поиска предназначен для интеграции с Telegram-ботом, который обрабатывает текстовые сообщения пользователей как запросы к RAG-системе. Модуль выполняет поиск релевантных данных, формирует контекст в формате JSON и передаёт его в модель AI (по умолчанию gpt-4o-mini) для генерации ответа. Ответ возвращается пользователю в Telegram с указанием источника, если он доступен.

Функциональность

  1. Обработка сообщений:
  2. Поиск данных:
  3. Формирование контекста:
  4. Генерация ответа:
  5. Отправка ответа:

Требования

Конфигурация

Модуль требует настройки следующих параметров:

Обработка запросов

  1. Получение сообщения:
  2. Векторный поиск:
  3. Ключевой поиск:
  4. Формирование контекста:
  5. Запрос к AI:
  6. Отправка ответа:

Формат ответа

Политика для user001 разрешает доступ к документам в папках /folder1 и /folder3.

Источник: role_policy.pdf

в документах нет необходимой информации для ответа на этот вопрос, но, основываясь на контексте, облачное хранилище позволяет хранить данные на удаленных серверах.

Зависимости

Модуль использует следующие Python-библиотеки:

Предобученные модели

Файлы

Примеры использования

Пример 1: Запрос политики доступа

Сообщение в Telegram:

Какая политика для user001?

 

Ответ бота:

Политика для user001 разрешает доступ к документам в папках /folder1 и /folder3.

Источник: role_policy.pdf

 

Пример 2: Запрос без релевантного контекста

Сообщение в Telegram:

Как работает облачное хранилище?

 

Ответ бота:

в документах нет необходимой информации для ответа на этот вопрос, но, основываясь на контексте, облачное хранилище позволяет хранить данные на удаленных серверах, обеспечивая доступ через интернет и высокую масштабируемость.

 

Пример 3: Ошибка API

Сообщение в Telegram:

Что такое API?

 

Ответ бота (при ошибке):

[Ошибка OpenAI: Invalid API key]

Документация чат-виджета интеграции

Эта документация описывает функциональность и процесс интеграции визуального чат-виджета, предназначенного для быстрого встраивания в HTML/JS интерфейсы. Виджет предоставляет стандартный интерфейс чата для взаимодействия с пользователем и поддерживает интеграцию с серверным API.

Содержание

  1. Назначение
  2. Интеграция
  3. Требования
  4. Стилизация
  5. Примеры использования
  6. Ограничения

Назначение

Чат-виджет предназначен для интеграции в веб-приложения, предоставляя пользователю удобный интерфейс для взаимодействия с серверной частью через API (например, с RAG-системой или прямым AI-чатом). Виджет поддерживает два режима отображения: плавающий (floating) и встроенный (embedded), обеспечивая гибкость для различных сценариев использования.

Интеграция

Виджет встраивается в HTML-страницу с помощью одной строки <script> с указанием необходимых параметров. Код виджета автоматически загружает стили и логику для работы чата.

Варианты встраивания

  1. Плавающий режим (data-mode="floating")
  2. Встроенный режим (data-mode="embedded")

Параметры конфигурации

Параметры задаются через атрибуты data-* в теге <script>:

По адресу localhost:3000/ - доступен конфигуратор виджета, который поможет определить оптимальные настройки для интеграции виджета

Пример тега <script>

html

<script src="chat-widget.js" data-api="http://localhost:3000/chat" data-mode="floating" data-width="400px" data-height="500px" defer></script>

 

Требования

Стилизация

Виджет использует встроенные CSS-стили, добавляемые динамически в <head> страницы. Основные классы и их назначение:

Стили по умолчанию

css

.cb-container {

  font-family: sans-serif;

  display: flex;

  flex-direction: column;

  border: 1px solid #ccc;

  border-radius: 12px;

  overflow: hidden;

  background: white;

}

.cb-float-btn {

  position: fixed;

  bottom: 20px;

  right: 20px;

  background: #4A90E2;

  color: white;

  border-radius: 50%;

  width: 60px;

  height: 60px;

  font-size: 30px;

  border: none;

  cursor: pointer;

  z-index: 999;

}

.cb-float-window {

  position: fixed;

  bottom: 90px;

  right: 20px;

  z-index: 9999;

  background: white;

  border-radius: 12px;

  box-shadow: 0 4px 12px rgba(0,0,0,0.2);

}

 

Примеры использования

Пример 1: Плавающий режим

HTML:

html

<!DOCTYPE html>

<html>

<head>

  <title>Чат-виджет</title>

</head>

<body>

  <h1>Моя страница</h1>

  <script src="chat-widget.js" data-api="http://localhost:3000/chat" data-mode="floating" data-width="400px" data-height="500px" defer></script>

</body>

</html>

 

Описание:

Пример ответа:

API (Application Programming Interface) — это интерфейс, который позволяет различным программам взаимодействовать друг с другом, обмениваясь данными или функциями.

 

Пример 2: Встроенный режим

HTML:

html

<!DOCTYPE html>

<html>

<head>

  <title>Чат-виджет</title>

</head>

<body>

  <h1>Моя страница</h1>

  <div id="chat-widget-root"></div>

  <script src="chat-widget.js" data-api="http://localhost:3000/chat" data-mode="embedded" data-parent="chat-widget-root" defer></script>

</body>

</html>

 

Описание:

Пример ответа:

Облачное хранилище позволяет хранить данные на удаленных серверах, обеспечивая доступ через интернет и высокую масштабируемость.

 

Пример 3: Запрос с Markdown-форматированием

HTML (плавающий режим):

html

<!DOCTYPE html>

<html>

<head>

  <title>Чат-виджет</title>

</head>

<body>

  <script src="chat-widget.js" data-api="http://localhost:3000/chat" data-mode="floating" defer></script>

</body>

</html>

 

Запрос пользователя: “Опиши структуру REST API” Пример ответа (с Markdown):

REST API — это архитектурный стиль для создания веб-сервисов. Основные принципы:

- Клиент-сервер: Разделение интерфейса и серверной логики.

- Без состояния: Каждый запрос независим.

- Кэшируемость: Ответы могут кэшироваться для оптимизации.

- Слои: Возможна многослойная архитектура.

- Единообразие интерфейса: Стандартизированные методы (GET, POST, PUT, DELETE).

 

Стартовая конфигурация



В следующей статье мы подробно расскажем как о методах реализации RAG систем

Что дальше?

Протестируй прямо сейчас

Добавьте файлы и протестируйте RAG прямо сейчас!