ComoRAG：用于长篇叙事推理的认知记忆检索工具

ComoRAG是一个为解决长篇文档和多文档叙事理解而设计的检索增强生成（RAG）系统。传统的RAG方法在处理长篇故事或小说时，由于情节复杂、人物关系不断演变，常常会遇到困难。 这是因为它们大多采用无状态、单次检索的方式，难以捕捉长距离的上下文关联。 ComoRAG的设计灵感来源于人类的认知过程，它认为叙事推理不是一次完成的，而是一个动态的、不断发展的过程，需要将新获取的证据与已有的知识进行整合。 当遇到推理困难时，ComoRAG会启动一个迭代推理循环。 它会生成探测式问题来探索新的线索，并将新检索到的信息整合到一个全局记忆池中，逐步为最初的问题构建一个连贯的上下文。 这种“推理→探测→检索→整合→解决”的循环模式，使其在处理需要全局理解的复杂问题时表现尤其出色。

Lista de funções

• 认知记忆框架：模仿人类大脑处理信息的方式，通过迭代推理循环处理复杂问题，实现动态、有状态的推理过程。
• Suporte a vários modelos：集成并支持多种大型语言模型（LLM）和嵌入模型，用户可以连接到OpenAI API，也可以部署本地的vLLM服务器和嵌入模型。
• 图增强检索：利用图结构进行检索和推理，更好地捕捉和理解实体之间的复杂关系。
• 灵活的数据处理：提供文档分块工具，支持按token、单词、句子等多种方式进行切分。
• Design modular：系统采用模块化和可扩展的设计，方便用户进行二次开发和功能扩展。
• Avaliação automatizada：自带评估脚本，支持F1、EM（精确匹配）等多种指标，方便对问答效果进行量化评估。

Usando a Ajuda

ComoRAG 是一个功能强大的检索增强生成框架，主要用于处理长篇叙事文本的理解和推理。它通过独特的认知迭代循环，显著提升了模型在长文本问答、信息抽取等任务上的表现。

环境配置与安装

在开始使用之前，你需要先配置好运行环境。

1. Versão Python：建议使用 Python 3.10 ou superior.
2. Instalação de dependências：克隆项目代码后，在项目根目录下通过以下命令安装所有必需的依赖包。推荐使用GPU环境以获得更好的性能。

   pip install -r requirements.txt
   

3. variável de ambiente：如果你计划使用OpenAI的API，需要设置相应的环境变量 OPENAI_API_KEY。如果使用本地模型，则需要配置模型的路径。

Preparação de dados

ComoRAG 需要特定格式的数据文件才能运行。你需要准备语料库文件和问答文件。

1. 语料库文件 (corpus.jsonl)：这个文件包含了所有需要被检索的文档。文件为 jsonl 格式，每一行是一个JSON对象，代表一篇文档。
   • id: 文档的唯一标识符。
   • doc_id: 文档所属的组或书籍的标识。
   • title: 文档标题。
   • contents: 文档的原始内容。

   Exemplo:

   {"id": 0, "doc_id": 1, "title": "第一章", "contents": "很久很久以前..."}
   

2. 问答文件 (qas.jsonl)：这个文件包含了需要模型回答的问题。同样，每一行是一个JSON对象。
   • id: 问题的唯一标识符。
   • question: 具体的问题。
   • golden_answers: 问题的标准答案列表。

   Exemplo:

   {"id": "1", "question": "故事的主角是谁？", "golden_answers": ["灰姑娘"]}
   

Agrupamento de documentos

由于长文档无法被模型直接处理，需要先将其切分成小块。项目提供了 chunk_doc_corpus.py 脚本来完成这个任务。

你可以使用以下命令对语料库进行分块：

python script/chunk_doc_corpus.py \
--input_path dataset/cinderella/corpus.jsonl \
--output_path dataset/cinderella/corpus_chunked.jsonl \
--chunk_by token \
--chunk_size 512 \
--tokenizer_name_or_path /path/to/your/tokenizer

• --input_path: 原始语料库文件的路径。
• --output_path: 分块后文件的保存路径。
• --chunk_by: 分块依据，可以是 tokeneword talvez sentence.
• --chunk_size: 每个分块的大小。
• --tokenizer_name_or_path: 指定用于计算token的分词器路径。

两种运行模式

ComoRAG 提供了两种主流的运行方式：使用OpenAI API或使用本地部署的vLLM服务器。

模式一：使用OpenAI API

这是最简单快捷的启动方式。

1. 修改配置: Aberto main_openai.py encontre o arquivo BaseConfig 部分进行修改。

   config = BaseConfig(
   llm_base_url='https://api.openai.com/v1',  # 通常无需修改
   llm_name='gpt-4o-mini',                    # 指定使用的OpenAI模型
   dataset='cinderella',                      # 数据集名称
   embedding_model_name='/path/to/your/embedding/model', # 指定嵌入模型的路径
   embedding_batch_size=32,
   need_cluster=True,                         # 启用语义/情景增强
   output_dir='result/cinderella',            # 结果输出目录
   ...
   )
   

2. programa de corrida：配置完成后，直接运行该脚本。

   python main_openai.py
   

模式二：使用本地vLLM服务器

如果你拥有足够的计算资源（如GPU），并希望在本地运行模型以保证数据隐私和降低成本，可以选择此模式。

1. 启动vLLM服务器：首先，你需要启动一个与OpenAI API兼容的vLLM服务器。

   python -m vllm.entrypoints.openai.api_server \
   --model /path/to/your/model \
   --served-model-name your-model-name \
   --tensor-parallel-size 1 \
   --max-model-len 32768
   

   • --model: 你本地大语言模型的路径。
   • --served-model-name: 为你的模型服务指定一个名称。
   • --tensor-parallel-size: 使用的GPU数量。
2. 检查服务器状态：你可以用 curl http://localhost:8000/v1/models 命令来检查服务器是否成功启动。
3. 修改配置: Aberto main_vllm.py 文件，修改其中的配置。

   # vLLM服务器配置
   vllm_base_url = 'http://localhost:8000/v1'
   served_model_name = '/path/to/your/model' # 与vLLM启动时指定的模型路径一致
   config = BaseConfig(
   llm_base_url=vllm_base_url,
   llm_name=served_model_name,
   llm_api_key="EMPTY",  # 本地服务器不需要真实的API Key
   dataset='cinderella',
   embedding_model_name='/path/to/your/embedding/model', # 本地嵌入模型路径
   ...
   )
   

4. programa de corrida：配置完成后，运行脚本。

   python main_vllm.py
   

Resultados da avaliação

当程序运行结束后，生成的结果会保存在 result/ 目录下。你可以使用 eval_qa.py 脚本来自动评估模型的表现。

python script/eval_qa.py /path/to/result/<dataset>/<subset>

该脚本会计算EM（精确匹配率）和F1分数等指标，并生成 results.json etc.

cenário do aplicativo

1. 长篇小说/剧本分析
   对于作家、编剧或文学研究者，ComoRAG可以作为一个强大的分析工具。用户可以导入整部小说或剧本，然后提出关于情节发展、人物关系演变或特定主题的复杂问题，系统能够通过整合全文信息给出深刻的见解。
2. 企业级知识库问答
   企业内部通常有大量的技术文档、项目报告和规章制度。ComoRAG可以处理这些长篇、复杂且互相关联的文档，构建一个智能问答系统。员工可以直接用自然语言提问，例如“在第三季度的项目中，A方案和B方案的技术实现有哪些关键差异和风险？”，系统能够整合多个报告，提供精准答案。
3. 法律文书和案件卷宗研读
   律师和法务人员需要阅读大量冗长的法律文书和历史卷宗。ComoRAG可以帮助他们快速梳理案件时间线，分析不同证据之间的关联，并回答需要综合多份文件才能得出结论的复杂问题，极大地提升了案件分析的效率。
4. 科学研究与文献综述
   科研人员在进行文献综述时，需要阅读和理解大量的学术论文。ComoRAG可以辅助研究人员对一个领域内的多篇论文进行提问，抽取关键信息，并构建知识图谱，帮助他们快速掌握研究领域的全局动态和核心挑战。

QA

1. ComoRAG与传统的RAG方法有什么核心区别？
   核心区别在于ComoRAG引入了一个受认知科学启发的动态迭代推理过程。 传统RAG通常是一次性的、无状态的检索，而ComoRAG在遇到难以解答的问题时，会主动生成新的探索性问题，进行多轮检索和信息整合，形成一个不断丰富的“记忆池”来辅助最终的推理。
2. 使用本地vLLM服务器有什么要求？
   使用vLLM本地服务器通常需要配备性能较好的NVIDIA GPU和足够的显存，具体要求取决于你所加载模型的大小。同时，需要安装CUDA工具包。这种方式虽然初始设置复杂，但可以提供更高的数据安全性和更快的推理速度。
3. 我可以替换自己的嵌入模型吗？
   可以。ComoRAG的架构是模块化的，你可以方便地在 embedding_model 目录下添加对新嵌入模型的支持。只需要确保你的模型能够将文本转换为向量，并适配系统的数据加载和调用接口即可。
4. 这个框架支持处理图片或音视频等多模态数据吗？
   从项目的基本介绍来看，ComoRAG目前主要专注于处理长文本叙事，例如长文档和多文档问答。 虽然其模块化设计为未来扩展多模态能力提供了可能，但当前版本的核心功能是围绕文本数据构建的。