Warlock Pain - Чат-бот по персонажу Destiny

Этот проект представляет собой диалогового ИИ-чат-бота, который воплощает "Пейна", персонажа-Варлока из игровой вселенной Destiny. Чат-бот использует подход Retrieval Augmented Generation (RAG) для предоставления ответов в соответствии с характером персонажа, черпая знания из специальных файлов с информацией о персонаже и мире.

Возможности

• Общение в роли персонажа: Общайтесь с Пейном, который отвечает в соответствии со своей определенной личностью и лором.
• Retrieval Augmented Generation (RAG): Использует ChromaDB в качестве векторного хранилища для извлечения релевантного контекста из документов с лором персонажа и мира, улучшая качество и точность ответов.
• Контекстуальная осведомленность: Ответы основаны на предоставленном лоре, обеспечивая соответствие вселенной Destiny.
• Управление историей чата: Использует MessagesState и MemorySaver из LangGraph для сохранения истории диалога для контекстуально связных взаимодействий. История обрезается до настраиваемого количества сообщений.
• Настраиваемая LLM: Легко адаптируется к другим моделям.
• Интерфейс командной строки (CLI): Взаимодействуйте с чат-ботом прямо из вашего терминала.
• Постоянное векторное хранилище: База данных ChromaDB сохраняется локально в каталоге chroma_db, что позволяет избежать повторной обработки исходных документов при каждом запуске.
• API-сервер (FastAPI): Предоставляет HTTP-эндпоинт для взаимодействия с чат-ботом, позволяя интегрировать его с другими приложениями.

Технологический стек

• Python 3.x
• Langchain & LangGraph: Для создания основной логики LLM-приложения, управления состоянием и определения диалогового потока.
• ChromaDB: Векторная база данных для хранения и извлечения эмбеддингов документов с лором.
• HuggingFace Sentence Transformers: Для генерации эмбеддингов (в частности, sentence-transformers/all-MiniLM-L6-v2).
• OpenAI-совместимый API: Для взаимодействия с большой языковой моделью (например, DeepSeek через Openrouter). langchain-openai используется для клиента ChatOpenAI.
• python-dotenv: Для управления переменными окружения (API-ключи и т.д.).
• FastAPI: Для создания API-сервера.
• Uvicorn: ASGI-сервер для запуска FastAPI-приложения.

Установка и настройка

1. Предварительные требования:

   • Python 3.8 или выше.
   • pip (установщик пакетов Python).

2. Клонировать репозиторий (необязательно): Если у вас этот проект в Git-репозитории, клонируйте его:

   git clone <your-repository-url>
   cd warlock_pain_chatbot # Или имя вашего каталога проекта

3. Создать и активировать виртуальное окружение (рекомендуется):

   python -m venv venv

   • В Windows:

     venv\Scripts\activate

   • В macOS/Linux:

     source venv/bin/activate

4. Установить зависимости:

   pip install -r requirements.txt

5. Настроить переменные окружения:

   • Создайте файл с именем .env в корне проекта.
   • Добавьте ваши учетные данные LLM API в этот файл. Например, если используется модель DeepSeek через OpenAI-совместимую конечную точку:

     LLM_BASE_URL="YOUR_LLM_API_BASE_URL"
     LLM_API_KEY="YOUR_LLM_API_KEY"
     LLM_NAME="YOUR_LLM_NAME"

     Замените YOUR_LLM_API_BASE_URL,YOUR_LLM_API_KEY и YOUR_LLM_NAME данными от используемой LLM.

Запуск приложения

1. Убедитесь, что ваше виртуальное окружение активировано.
2. Перейдите в корневой каталог проекта в вашем терминале.

Запуск CLI-чата

1. Запустите основной скрипт:

   python main.py

2. Вы увидите приветственное сообщение.
3. Вводите свои сообщения и нажимайте Enter, чтобы общаться с Пейном.
4. Чтобы выйти из чата, введите выход или quit.

Запуск API-сервера

1. Запустите FastAPI-сервер с помощью Uvicorn:

   uvicorn api_server:fastapi_app --reload

   • api_server: Имя Python-файла, содержащего FastAPI-приложение (api_server.py).
   • fastapi_app: Имя экземпляра FastAPI в файле api_server.py.
   • --reload: Флаг для автоматического перезапуска сервера при изменениях в коде (удобно для разработки).

2. Сервер будет доступен по умолчанию на http://127.0.0.1:8000.

3. Вы можете взаимодействовать с API через эндпоинт /chat.

Эндпоинт API: /chat

• Метод: POST

• Описание: Отправляет сообщение чат-боту и получает ответ.

• Тело запроса (JSON):

  {
    "thread_id": "string",  // Уникальный идентификатор для отслеживания истории диалога
    "message": "string"     // Сообщение пользователя
  }

• Ответ (JSON):

  {
    "character_name": "string", // Имя персонажа
    "response": "string"        // Ответ персонажа
  }

• Вы также можете получить доступ к интерактивной документации API (Swagger UI) по адресу http://127.0.0.1:8000/docs в вашем браузере после запуска сервера.

При первом запуске система обработает текстовые файлы в каталоге data, создаст эмбеддинги и сохранит их в базе данных ChromaDB, расположенной в каталоге chroma_db. Последующие запуски будут загружать существующую базу данных, ускоряя инициализацию.

Структура проекта

.
├── data/
│   ├── character_info.txt  # Лор и информация, специфичные для персонажа
│   └── world_info.txt      # Лор и информация, специфичные для мира
├── chroma_db/              # Каталог для постоянного хранения ChromaDB (создается автоматически)
├── .env                    # Переменные окружения (URL LLM API, ключ)
├── config.py               # Загружает переменные окружения из .env
├── llm_logic.py            # Определяет рабочий процесс LangGraph, инициализацию LLM, узел RAG и обрезку истории
├── main.py                 # Точка входа CLI для чат-приложения
├── api_server.py           # Реализация FastAPI-сервера для API-взаимодействия
├── prompts.py              # Содержит имя персонажа и основной промпт личности
├── vector_store.py         # Управляет созданием, загрузкой векторного хранилища ChromaDB и инициализацией ретривера
└── requirements.txt        # Зависимости пакетов Python

Кастомизация

• Персонаж:

  • Измените CHARACTER_NAME и CHARACTER_CORE_PERSONALITY в prompts.py, чтобы определить персонажа.
  • Обновите data/character_info.txt специфичным лором нового персонажа.

• LLM:

  • Обновите LLM_BASE_URL, LLM_API_KEY и LLM_NAME в вашем файле .env, если вы переключаетесь на другого провайдера LLM или конечную точку модели.
  • Отрегулируйте параметр temperature в llm_logic.py при инициализации ChatOpenAI, чтобы контролировать креативность ответов.

• Векторное хранилище и эмбеддинги:

  • Измените EMBEDDING_MODEL_NAME в vector_store.py, чтобы использовать другую модель sentence transformer из HuggingFace.
  • Отрегулируйте CHUNK_SIZE и CHUNK_OVERLAP в vector_store.py, чтобы точно настроить, как документы разбиваются перед созданием эмбеддингов. Это может повлиять на качество извлечения.
  • Измените PERSIST_DIRECTORY в vector_store.py, если вы хотите хранить файлы ChromaDB в другом месте.

• Промпты и логика:

  • Основной системный промпт, который объединяет личность, извлеченный контекст и инструкции, создается в функции retrieve_and_generate_node в llm_logic.py. Вы можете подробно настроить этот промпт.
  • Измените MAX_MESSAGES_HISTORY в llm_logic.py, чтобы изменить, сколько прошлых сообщений сохраняется в истории диалога. Обратите внимание, что текущая стратегия trim_messages для простоты подсчитывает сообщения, а не токены.

• Источники данных:

  • Вы можете добавить больше источников данных, создав новые экземпляры TextLoader в vector_store.py и добавив их документы в all_docs. Не забудьте назначить соответствующие метаданные (например, source), если вы хотите фильтровать или идентифицировать их позже.