基于Gemini与Hermes Agent构建长文本智能体工作流实战

1. 项目概述：当长文本工作流遇上智能体

最近在折腾一个挺有意思的项目，核心是把谷歌的Gemini大语言模型，集成到Hermes这个开源智能体框架里，专门用来处理那些动辄几万甚至几十万token的“长文本”工作流。简单来说，就是让AI智能体不仅能“听懂”你的指令，还能“记住”并“消化”一整本电子书、一份冗长的法律合同，或者一个包含数百条对话记录的客服日志，然后基于这些海量信息，帮你完成复杂的分析和任务。

为什么这个组合值得关注？因为在实际应用中，我们遇到的很多问题都不是三言两语能说清的。比如，你想让AI帮你分析一份上百页的行业研报，提炼出核心观点和投资建议；或者，你需要它通读一个软件项目的所有历史文档和代码注释，然后回答一个非常具体的架构问题。这些场景下，传统的、只能处理几千token的模型就“内存不足”了，它会直接告诉你“文本太长，我处理不了”。而Gemini系列模型，特别是其1.5 Pro版本，原生支持高达100万token的上下文长度，这就像给智能体换上了一块超大内存的“大脑”，让它有能力去啃下这些硬骨头。

Hermes Agent本身是一个设计精良的智能体框架，它提供了任务规划、工具调用、记忆管理等核心组件。但它的默认“大脑”（模型）可能并不擅长处理超长上下文，或者在长文本理解上的精度和效率不够理想。我这个项目的目标，就是为Hermes Agent换上Gemini这颗强大的“长文本引擎”，并围绕长上下文场景，设计一套稳定、高效的工作流。这不仅仅是换个API接口那么简单，它涉及到提示词工程、上下文窗口的智能管理、成本控制以及错误处理等一系列深层问题。接下来，我就把自己在搭建和优化这个“Gemini for Hermes”长文本工作流过程中的核心思路、实操细节以及踩过的坑，毫无保留地分享出来。

2. 核心架构与方案选型

2.1 为什么是Gemini + Hermes？

在决定技术栈时，我主要权衡了能力、成本、可控性和生态四个维度。首先看能力，处理长上下文是刚需。市面上支持长上下文的模型不少，比如Claude 3系列、GPT-4 Turbo，以及一些开源的模型。我选择Gemini 1.5 Pro，是因为它在官方基准测试和我的实际对比中，在长文档的QA、信息抽取和多步骤推理任务上，表现出了非常出色的稳定性和准确性。它的100万token上下文窗口是实打实的，不是理论值，这对于处理整本书或大型代码库至关重要。

其次，成本因素不容忽视。Gemini 1.5 Pro的定价模式对于长文本处理相对友好，特别是其“每百万token”的计价方式，在处理超长文档时，相比某些按请求次数或分段处理累计成本更高的方案，有时更具性价比。当然，成本控制需要精细的上下文管理策略，这部分后面会详细讲。

再者是可控性。Hermes Agent作为一个开源框架，给了我极大的定制自由。我可以深入其内部，修改任务规划逻辑、定制记忆存储方式，以及最关键的——集成任何我想要的模型后端。我不想被绑定在某个封闭的智能体服务里，Hermes+Gemini的组合，让我既能享受顶级模型的能力，又能完全掌控智能体的行为逻辑和数据处理流程。

最后是生态。Gemini API的稳定性、文档的清晰度，以及Hermes社区活跃度，都是加分项。Hermes基于Python，与我现有的技术栈完美契合，集成和调试起来非常顺畅。

2.2 长文本工作流的独特挑战与设计思路

直接把Gemini模型接入Hermes，然后扔给它一个长文档，是行不通的。长文本工作流至少面临三大核心挑战：

1. 上下文溢出与效率问题：即使模型支持100万token，每次交互都把整个长文档作为上下文发送，不仅速度慢、成本高，而且模型在如此庞大的信息中定位关键内容的能力也会下降。我们需要一种“按需取用”的机制。
2. 信息定位与检索精度：当用户问“在文档第50页提到的那个技术方案是什么？”时，智能体必须能快速、准确地找到相关片段。这需要强大的检索能力，而不是让模型漫无目的地通读全文。
3. 多轮对话中的状态维持：在复杂的多轮交互中，如何让智能体记住之前讨论过的、分散在长文档不同位置的信息点，并保持对话逻辑的连贯性？

我的设计思路是采用“检索增强生成（RAG） + 动态上下文管理”的核心架构。具体来说：

• 预处理与索引阶段：将长文档（如PDF、Word、Markdown）进行智能分块（Chunking），不是简单地按字数切割，而是尽量保证语义的完整性（比如按章节、段落）。然后使用嵌入模型（Embedding Model）为每个文本块生成向量，存入向量数据库（如Chroma、Weaviate）。
• 交互与执行阶段：当用户提出问题时，Hermes Agent首先进行任务规划。如果判断问题涉及长文档知识，则触发检索流程：将用户问题也转化为向量，在向量数据库中查找最相关的几个文本块。
• 动态上下文构建：仅将这些检索到的、高相关性的文本块，连同清晰的系统指令、对话历史（最近几轮）和当前问题，一起构建成最终的提示词（Prompt），发送给Gemini模型。这样就实现了“大库存储，小窗问答”，既利用了长文档的全部信息，又保证了每次交互的效率和精度。
• 记忆与状态管理：利用Hermes Agent自身的记忆模块，记录关键对话历史和决策点，确保多轮对话的连贯性。对于超长对话，可以采用摘要记忆的方式，将过往长对话压缩成要点存入记忆。

这个架构将Gemini强大的理解和生成能力，与RAG的高效检索能力，通过Hermes Agent的调度完美结合了起来。

3. 环境搭建与核心集成

3.1 基础环境配置

首先，确保你的Python环境在3.9以上。我强烈建议使用虚拟环境（如venv或conda）来管理依赖，避免包冲突。

# 创建并激活虚拟环境 python -m venv herm source herm/bin/activate # Linux/Mac # herm\Scripts\activate # Windows # 安装核心框架 pip install hermes-agent

Hermes Agent是核心框架。接下来，我们需要安装Gemini的官方SDK，以及处理长文档和向量检索相关的库。

pip install google-generativeai # Gemini官方SDK pip install chromadb # 轻量级向量数据库，用于本地存储和检索 pip install pypdf2 python-docx markdown # 用于解析PDF、Word、Markdown等格式的文档 pip install sentence-transformers # 用于生成文本嵌入，也可以使用Gemini的嵌入模型 pip install tiktoken # 用于精确计算token数量（虽然叫tiktoken，但可用于估算Gemini的token）

注意：sentence-transformers库会下载相应的预训练模型，首次使用可能需要一些时间。如果你追求更快的嵌入速度或想使用Gemini的嵌入模型，可以配置google-generativeai的嵌入功能，但需要注意其API调用成本。

3.2 Gemini模型接入Hermes Agent

Hermes Agent的设计允许灵活替换模型提供商。我们需要创建一个自定义的模型类，来封装与Gemini API的交互。

# gemini_provider.py import google.generativeai as genai from hermes.agent.models import BaseModel from typing import List, Dict, Any, Optional class GeminiModel(BaseModel): """Hermes Agent的Gemini模型提供商实现""" def __init__(self, model_name: str = "gemini-1.5-pro-latest", api_key: Optional[str] = None): """ 初始化Gemini模型。 Args: model_name: Gemini模型名称，如 'gemini-1.5-pro-latest', 'gemini-1.5-flash-latest' api_key: Gemini API密钥。如果为None，会尝试从环境变量GOOGLE_API_KEY读取。 """ if api_key is None: import os api_key = os.getenv("GOOGLE_API_KEY") if not api_key: raise ValueError("未提供Gemini API密钥，且环境变量GOOGLE_API_KEY未设置。") # 配置Gemini API genai.configure(api_key=api_key) self.model = genai.GenerativeModel(model_name) self.model_name = model_name def generate(self, messages: List[Dict[str, str]], **kwargs) -> str: """ 核心生成方法，将Hermes的消息格式转换为Gemini所需的格式。 Hermes的消息格式通常为: [{"role": "user/system/assistant", "content": "..."}, ...] Gemini的API通常期望一个字符串形式的提示，或特定的消息结构。 这里我们进行适配。 """ # 构建Gemini可接受的提示内容 # 简单策略：将对话历史拼接成一个连贯的文本，并明确角色。 prompt_parts = [] for msg in messages: role = msg.get("role", "user") content = msg.get("content", "") # 可以根据需要添加角色前缀，如“系统指令：”、“用户：”、“助手：” if role == "system": prompt_parts.append(f"系统指令：{content}") elif role == "user": prompt_parts.append(f"用户：{content}") elif role == "assistant": prompt_parts.append(f"助手：{content}") else: prompt_parts.append(content) # 用换行符连接所有部分，形成最终提示 full_prompt = "\n".join(prompt_parts) # 调用Gemini模型生成 try: # 可以传递额外的生成参数，如temperature, max_output_tokens等 generation_config = kwargs.get("generation_config", { "temperature": 0.7, "max_output_tokens": 2048, # 根据长文本回答的需要调整 }) response = self.model.generate_content( full_prompt, generation_config=genai.types.GenerationConfig(**generation_config) ) return response.text except Exception as e: # 处理可能的API错误，如超过上下文长度、内容安全拦截等 raise Exception(f"Gemini模型调用失败: {e}") def count_tokens(self, text: str) -> int: """估算文本的token数量（近似值）。""" # 注意：这是一个近似估算。更准确的方式是使用Gemini API的count_tokens方法。 # 这里使用tiktoken的cl100k_base编码器进行粗略估算，因为Gemini的tokenizer不公开。 import tiktoken encoding = tiktoken.get_encoding("cl100k_base") # GPT-4/Gemini近似使用此编码 return len(encoding.encode(text))

这个GeminiModel类继承了Hermes的BaseModel，并实现了generate方法。关键点在于消息格式的转换。Hermes内部使用类似OpenAI的role-content格式的消息列表，我们需要将其合理地拼接成Gemini API能接受的提示文本。上面的实现是一个基础版本，在实际长文本工作流中，我们可能会更精细地构造系统指令部分。

3.3 长文档处理与向量索引模块

这是长文本工作流的大脑“外置记忆库”。我们需要一个模块来处理文档加载、分块、向量化和检索。

# document_processor.py import os from typing import List, Tuple import PyPDF2 from docx import Document import markdown from bs4 import BeautifulSoup import chromadb from chromadb.config import Settings from sentence_transformers import SentenceTransformer class LongDocumentProcessor: def __init__(self, persist_directory: str = "./chroma_db", embedding_model_name: str = 'all-MiniLM-L6-v2'): """ 初始化长文档处理器。 Args: persist_directory: Chroma向量数据库持久化目录。 embedding_model_name: 句子嵌入模型名称。 """ self.embedding_model = SentenceTransformer(embedding_model_name) self.chroma_client = chromadb.PersistentClient(path=persist_directory, settings=Settings(allow_reset=True)) # 创建一个集合（类似数据库的表）来存储文档块 self.collection = self.chroma_client.get_or_create_collection(name="long_docs") def load_and_chunk_document(self, file_path: str, chunk_size: int = 1000, chunk_overlap: int = 200) -> List[str]: """加载文档并按语义分块。""" text = "" ext = os.path.splitext(file_path)[1].lower() if ext == '.pdf': text = self._read_pdf(file_path) elif ext == '.docx': text = self._read_docx(file_path) elif ext in ['.md', '.markdown', '.txt']: with open(file_path, 'r', encoding='utf-8') as f: text = f.read() if ext in ['.md', '.markdown']: # 将Markdown转换为纯文本 html = markdown.markdown(text) soup = BeautifulSoup(html, "html.parser") text = soup.get_text() else: raise ValueError(f"不支持的文档格式: {ext}") # 简单的按句子和重叠分块算法（可替换为更复杂的语义分块，如按段落、标题） sentences = text.replace('\n', ' ').split('. ') chunks = [] current_chunk = [] current_length = 0 for sentence in sentences: sentence_length = len(sentence.split()) if current_length + sentence_length > chunk_size and current_chunk: # 保存当前块 chunks.append('. '.join(current_chunk) + '.') # 保留重叠部分开始新块 overlap_sentences = current_chunk[-int(chunk_overlap/50):] # 粗略估算 current_chunk = overlap_sentences + [sentence] current_length = sum(len(s.split()) for s in current_chunk) else: current_chunk.append(sentence) current_length += sentence_length if current_chunk: chunks.append('. '.join(current_chunk) + '.') return chunks def _read_pdf(self, file_path: str) -> str: """读取PDF文件文本。""" text = "" with open(file_path, 'rb') as file: reader = PyPDF2.PdfReader(file) for page in reader.pages: text += page.extract_text() + "\n" return text def _read_docx(self, file_path: str) -> str: """读取Word文档文本。""" doc = Document(file_path) return "\n".join([para.text for para in doc.paragraphs]) def index_document(self, file_path: str, doc_id: str): """将文档分块、向量化并存入向量数据库。""" print(f"正在索引文档: {file_path}") chunks = self.load_and_chunk_document(file_path) # 为每个块生成嵌入向量 embeddings = self.embedding_model.encode(chunks).tolist() # 生成唯一的块ID chunk_ids = [f"{doc_id}_chunk_{i}" for i in range(len(chunks))] # 存入ChromaDB self.collection.add( embeddings=embeddings, documents=chunks, ids=chunk_ids, metadatas=[{"source": file_path, "chunk_index": i} for i in range(len(chunks))] ) print(f"文档索引完成，共{len(chunks)}个块。") def retrieve_relevant_chunks(self, query: str, top_k: int = 5) -> List[Tuple[str, float]]: """根据查询检索最相关的文档块。""" # 将查询语句也转化为向量 query_embedding = self.embedding_model.encode([query]).tolist()[0] # 在集合中查询 results = self.collection.query( query_embeddings=[query_embedding], n_results=top_k ) # 返回文档内容和相似度分数 retrieved_docs = results['documents'][0] distances = results['distances'][0] # 注意：Chroma返回的是距离，越小越相似 # 将距离转换为相似度分数（简单处理：1 / (1 + distance)） scores = [1 / (1 + d) for d in distances] return list(zip(retrieved_docs, scores))

这个处理器完成了从文档到可检索知识库的转换。index_document方法是核心，它负责解析、分块、向量化和存储。retrieve_relevant_chunks方法则是在用户提问时，快速从海量文本块中找出最相关的部分。

4. 智能体工作流构建与提示词工程

4.1 定制Hermes智能体与工具集成

现在，我们需要将文档检索能力封装成Hermes Agent可以调用的“工具”，并创建一个专门的智能体来协调整个长文本问答流程。

# long_context_agent.py from hermes.agent import Agent from hermes.agent.tools import tool from document_processor import LongDocumentProcessor from gemini_provider import GeminiModel import os class LongContextAgent: def __init__(self, gemini_api_key: str = None, db_path: str = "./chroma_db"): """ 初始化长上下文智能体。 Args: gemini_api_key: Gemini API密钥。 db_path: 向量数据库路径。 """ # 初始化模型和文档处理器 self.model = GeminiModel(api_key=gemini_api_key or os.getenv("GOOGLE_API_KEY")) self.doc_processor = LongDocumentProcessor(persist_directory=db_path) # 定义检索工具 @tool def retrieve_from_docs(query: str) -> str: """ 从已索引的长文档中检索与问题最相关的信息片段。 Args: query: 用户的问题或需要查询的关键信息。 Returns: 返回检索到的相关文本片段，并附带相关性评分。 """ chunks_with_scores = self.doc_processor.retrieve_relevant_chunks(query, top_k=3) if not chunks_with_scores: return "未在已索引的文档中找到相关信息。" result_parts = [] for i, (chunk, score) in enumerate(chunks_with_scores): result_parts.append(f"[片段 {i+1}, 相关性: {score:.3f}]\n{chunk}\n") return "\n---\n".join(result_parts) # 将工具函数赋值给实例，以便Agent访问 self.retrieve_tool = retrieve_from_docs # 构建系统提示词（核心！） system_prompt = """你是一个专门处理长文档的专家助手。你的知识来源于用户已上传并索引的文档库。 当用户提出问题时，请遵循以下步骤： 1. **理解与规划**：仔细分析用户问题，判断是否需要从文档库中检索信息。如果问题涉及具体事实、数据、概念或文档中的特定内容，则必须使用`retrieve_from_docs`工具进行检索。 2. **检索与整合**：使用工具检索到相关片段后，仔细阅读这些片段。它们是你回答问题的唯一依据。不要依赖工具返回内容之外的知识。 3. **精准回答**：基于检索到的信息，组织清晰、准确、完整的回答。如果信息不足以完全回答问题，请明确指出缺失的部分，并可以建议用户提供更具体的查询或上传更多相关文档。 4. **引用来源**：在回答中，可以提及信息来源于文档的哪个片段（例如，“根据检索到的片段1...”），以增加可信度。 5. **处理模糊**：如果用户问题很模糊，或者检索结果不相关，请主动询问澄清，而不是猜测。 记住：你的核心能力是理解和整合长文档中的信息，而不是通用知识问答。对于与文档无关的通用问题，你可以礼貌地说明你的职责范围。 """ # 创建Hermes Agent实例 self.agent = Agent( model=self.model, tools=[self.retrieve_tool], # 将检索工具提供给Agent system_prompt=system_prompt ) def index_document(self, file_path: str, doc_id: str): """对外暴露的文档索引方法。""" self.doc_processor.index_document(file_path, doc_id) def ask(self, question: str) -> str: """向智能体提问。""" response = self.agent.run(question) return response

这个LongContextAgent类是整个项目的枢纽。它内部创建了一个Hermes Agent，并为其配备了一个关键的检索工具retrieve_from_docs。最精髓的部分在于系统提示词（system_prompt），它明确规定了智能体在长文本问答场景下的行为准则：优先检索、基于证据回答、保持诚实。这直接决定了智能体工作流的质量。

4.2 长上下文提示词构建策略

在GeminiModel.generate方法中，我们简单拼接了消息。但在实际的长文本工作流中，提示词的构建需要更精细的策略，以优化Gemini模型的表现并控制成本。

我们需要修改GeminiModel.generate方法，使其能更好地处理包含长上下文（检索结果）的提示：

# 在gemini_provider.py的GeminiModel类中，优化generate方法 def generate(self, messages: List[Dict[str, str]], **kwargs) -> str: """ 优化后的生成方法，专门处理可能包含长上下文的对话。 """ # 分离系统指令、对话历史和最新的用户问题 system_instructions = [] conversation_history = [] latest_user_query = None for msg in messages: role = msg.get("role") content = msg.get("content", "") if role == "system": system_instructions.append(content) elif role == "user": # 我们假设最后一条用户消息是当前问题 latest_user_query = content # 之前的用户消息放入历史 if latest_user_query != content: # 如果不是同一条 conversation_history.append(f"用户：{content}") elif role == "assistant": conversation_history.append(f"助手：{content}") # 构建最终提示 prompt_parts = [] # 1. 系统指令（放在最前面，明确角色和规则） if system_instructions: # 合并所有系统指令 full_system_instruction = "\n".join(system_instructions) prompt_parts.append(f"系统指令（请严格遵守）：\n{full_system_instruction}") # 2. 如果有对话历史，附上最近几轮以保持连贯性（避免太长） if conversation_history: # 只保留最近3轮对话历史，防止上下文过长 recent_history = conversation_history[-6:] # 假设每轮包含用户和助手各一条 prompt_parts.append("最近的对话历史：") prompt_parts.extend(recent_history) # 3. 当前用户问题（这是模型需要回应的核心） if latest_user_query: prompt_parts.append(f"当前用户问题：{latest_user_query}") # 4. 添加一个明确的指令，要求模型基于上述信息回答 prompt_parts.append("请基于系统指令、对话历史（如果有）和当前问题，给出你的回答。确保回答准确、完整，并严格遵循系统指令的要求。") full_prompt = "\n\n".join(prompt_parts) # 在发送前，可以估算token并记录（用于成本监控和调试） estimated_tokens = self.count_tokens(full_prompt) print(f"[DEBUG] 本次请求预估Token数: {estimated_tokens}") # 调用Gemini API try: generation_config = genai.types.GenerationConfig( temperature=0.2, # 长文本任务，降低随机性，提高准确性 max_output_tokens=4096, # 根据回答长度需要调整 top_p=0.95, ) response = self.model.generate_content(full_prompt, generation_config=generation_config) return response.text except Exception as e: # 特别处理上下文过长错误（虽然Gemini 1.5支持很长，但以防万一） if "context length" in str(e).lower(): raise Exception("请求上下文长度可能超出模型限制，请尝试简化问题或检索更精确的片段。") raise Exception(f"模型调用失败: {e}")

这个优化版的提示词构建策略，结构更清晰，角色指令更突出，并且加入了Token估算的调试信息，对于长上下文工作流的稳定运行至关重要。

5. 完整工作流演示与实战

5.1 端到端流程：从文档上传到智能问答

让我们用一个完整的例子，串联起所有模块。假设我们有一份名为AI_Report_2024.pdf的行业报告，想通过智能体来问答。

# main_demo.py import os from long_context_agent import LongContextAgent def main(): # 0. 设置你的Gemini API密钥（最好通过环境变量） # os.environ["GOOGLE_API_KEY"] = "your_api_key_here" # 1. 初始化长上下文智能体 print("初始化长上下文智能体...") agent = LongContextAgent(db_path="./my_document_db") # 2. 索引长文档（只需做一次） report_path = "./documents/AI_Report_2024.pdf" if os.path.exists(report_path): print(f"开始索引文档: {report_path}") agent.index_document(report_path, doc_id="ai_report_2024") print("文档索引完成！") else: print(f"文档不存在: {report_path}，请准备示例文档。") # 这里可以创建一个示例文本文件用于演示 with open("./documents/sample.txt", "w", encoding='utf-8') as f: f.write("""人工智能在2024年的主要趋势包括多模态大模型、Agent智能体的普及、以及AI在科学发现中的应用加速。 大型语言模型如Gemini、GPT-4等正朝着更长的上下文窗口发展，以处理书籍、长代码库等复杂信息。 成本优化和效率提升是企业和研究机构关注的重点。""") agent.index_document("./documents/sample.txt", doc_id="sample_trends") # 3. 开始交互式问答 print("\n--- 智能体就绪，可以开始提问（输入'quit'退出）---") while True: try: user_input = input("\n你的问题: ").strip() if user_input.lower() in ['quit', 'exit', 'q']: print("再见！") break if not user_input: continue print("\n[智能体思考中...]") # 4. 智能体运行：内部会触发检索、规划、生成完整流程 answer = agent.ask(user_input) print(f"\n助手: {answer}") except KeyboardInterrupt: print("\n程序被中断。") break except Exception as e: print(f"\n出错: {e}") if __name__ == "__main__": main()

运行这个脚本，你会看到智能体先索引文档，然后进入交互模式。当你问“2024年AI的主要趋势有哪些？”时，智能体会自动调用retrieve_from_docs工具，从向量库中找到相关段落，然后基于这些信息生成回答。

5.2 复杂任务处理示例：多步骤分析与总结

长文本智能体的强大之处在于处理需要多步骤推理的复杂任务。假设文档是一本软件工程书籍，用户可以要求：

• 任务1：对比分析- “请比较书中提到的‘微服务架构’和‘单体架构’的优缺点，并列出各自适用的场景。”
• 任务2：概念解释与举例- “用书中的观点解释一下‘领域驱动设计（DDD）’中的‘限界上下文’概念，并给出一个例子。”
• 任务3：基于文档的创作- “根据本书第三章节关于‘代码重构’的原则，帮我起草一份给开发团队的代码审查清单。”

对于这些任务，智能体的工作流如下：

1. 任务解析：Hermes Agent理解到这是一个需要从文档中提取、对比、总结信息的复杂任务。
2. 规划与工具调用：它可能会规划多个子步骤。例如，对于任务1，它可能先分别检索“微服务架构优缺点”和“单体架构优缺点”，然后再检索“适用场景”。
3. 信息整合：Gemini模型收到包含多个检索片段的上下文后，进行综合对比、分析，按照指令生成结构化的回答（如表格、列表）。
4. 生成输出：最终输出一份清晰、有据可循的答案。

在这个过程中，系统提示词里“基于检索到的信息回答”的指令至关重要，它约束了模型不要随意发挥，保证了回答的忠实性。

6. 性能优化、成本控制与问题排查

6.1 性能优化技巧

1. 分块策略优化：简单的按句子/字数分块可能割裂语义。更好的方法是使用语义分块，例如利用自然段落、标题（#）或特定分隔符。可以使用langchain的RecursiveCharacterTextSplitter，它能在尽量保持段落、句子完整性的前提下分块。
2. 嵌入模型选择：all-MiniLM-L6-v2是一个不错的通用选择，平衡了速度和效果。对于更高精度要求，可以考虑all-mpnet-base-v2。如果想用Gemini自家的嵌入模型（text-embedding-004），虽然精度可能更高且与Gemini模型生态更契合，但需注意API调用成本。
3. 检索优化：
   • 混合搜索：结合向量相似性搜索（语义）和关键词搜索（如BM25），可以提高检索的召回率，尤其是当用户使用特定术语时。
   • 重排序（Re-ranking）：先用向量检索出Top K（如20个）候选块，再用一个更小、更快的重排序模型对它们进行精排，选出最相关的Top N（如3个）送给LLM。这能显著提升最终答案的质量。
   • 元数据过滤：在索引时，为每个块添加丰富的元数据（如章节标题、页码、文档类型）。检索时，可以先根据元数据过滤（例如，“只在第三章里找”），再进行向量搜索，能极大提升效率和精度。
4. 上下文窗口管理：尽管Gemini 1.5支持超长上下文，但塞入过多不相关信息会干扰模型。要严格控制送入模型的上下文总长度。一个实用的公式是：系统指令 + 最近对话历史（2-3轮） + 检索到的Top N个块 + 当前问题 < 模型上下文上限 * 安全系数（如0.8）。需要为模型的回答预留空间（max_output_tokens）。

6.2 成本控制实战

使用Gemini API，成本主要来自两个方面：生成（输出）Token和输入Token。在长文本工作流中，输入Token的成本占比往往很高，因为每次都要发送系统指令、历史、检索结果和问题。

成本控制策略：

1. 精细化检索：这是最有效的省钱方法。通过优化分块、嵌入和检索策略，确保每次只送入最相关、最精简的文本块。检索Top K的K值不要盲目设大，通常3-5个高质量块远好于10个一般相关的块。
2. 缓存检索结果：对于相同或相似的查询，可以缓存其检索结果和生成的回答，避免重复调用模型和嵌入模型。可以使用简单的键值对缓存（如functools.lru_cache）或Redis。
3. 对话历史摘要：对于非常长的多轮对话，不要将全部历史对话都放入上下文。可以定期（例如每5轮）用模型对之前的对话历史生成一个简短的摘要，然后用摘要代替原始长历史。这能大幅节省输入Token。
4. 监控与预算：在代码中集成Token计数，并记录每次API调用的预估成本。可以设置每日或每月的预算告警。
5. 模型选型：对于不需要极强推理能力、但需要处理大量文本的简单问答或摘要任务，可以考虑使用更便宜、更快的模型，如gemini-1.5-flash-latest。

6.3 常见问题与排查实录

在实际部署和测试中，我遇到了以下几个典型问题及解决方法：

问题1：智能体不调用检索工具，直接基于自身知识回答。

• 现象：即使问了文档中的具体内容，智能体也泛泛而谈，日志显示没有调用retrieve_from_docs工具。
• 排查：检查系统提示词。问题通常出在提示词没有给智能体明确的“必须检索”的指令。确保提示词中有类似“如果问题涉及文档内容，你必须使用retrieve_from_docs工具”的强约束。
• 解决：强化系统提示词中的工具调用规则。可以加入思维链（Chain-of-Thought）式的引导，例如：“思考步骤：1. 分析问题是否与已索引文档有关。2. 如果有关，调用检索工具。3. 基于检索结果回答。”

问题2：检索到的内容不相关，导致回答跑偏。

• 现象：智能体调用了工具，但拿回来的文本片段与问题风马牛不相及，导致生成荒谬答案。
• 排查：
  • 分块质量：检查文档分块是否合理。一个块是否包含了完整的语义单元？如果一个问题涉及的概念被分割在两个块里，检索可能失败。尝试调整chunk_size和chunk_overlap，或改用语义分块。
  • 嵌入模型：当前的嵌入模型是否适合你的文档领域（如法律、医学、代码）？通用嵌入模型在专业领域可能表现不佳。考虑使用在该领域微调过的嵌入模型。
  • 查询改写：用户的原始问题可能不够“像”文档中的表述。可以尝试对用户问题进行查询扩展或改写，例如，提取问题中的关键词，或让一个轻量级模型将问题改写成更可能出现在文档中的陈述句，再用改写后的句子去检索。
• 解决：实施混合搜索（关键词+向量），并引入重排序模型。确保分块策略贴合文档结构。

问题3：处理超长PDF时，文本提取混乱或缺失。

• 现象：从PDF中提取的文本包含大量乱码、换行符错误，或丢失了表格、图表中的文字。
• 排查：PyPDF2对复杂PDF的解析能力有限。
• 解决：换用更强大的PDF解析库，如pdfplumber或pymupdf（fitz）。对于扫描版PDF，则需要OCR工具，如pytesseract配合pdf2image先将每一页转为图片再识别。

问题4：API调用超时或速率限制。

• 现象：请求长时间无响应或返回429错误。
• 排查：Gemini API有默认的速率限制。同时，如果检索到的上下文非常长，模型生成时间也会变长。
• 解决：
  • 实现重试机制：在API调用处添加指数退避的重试逻辑，处理暂时的网络问题或速率限制。
  • 设置超时：为API调用设置合理的超时时间（如30秒），并做好超时处理（例如，提示用户问题过于复杂或请重试）。
  • 异步处理：对于可能耗时的复杂任务，可以考虑将任务提交到后台队列异步处理，通过WebSocket或轮询通知用户结果。

问题5：多轮对话中，智能体“忘记”了之前讨论过的文档内容。

• 现象：在第一轮问答中提到了文档的A点，第二轮基于A点深入提问时，智能体似乎不记得了。
• 排查：检索是基于当前问题进行的。第二轮问题如果没有触发对A点相关内容的检索，模型上下文中就没有这些信息。
• 解决：这需要更高级的对话记忆管理。可以在系统提示词中要求模型在回答时，如果引用或推导出某个重要信息，可以主动建议将其“记住”（以关键词形式）。同时，可以利用Hermes Agent的记忆功能，将每轮问答的关键信息（如涉及的核心实体、结论）以结构化的方式存储下来。在后续提问时，可以将这些记忆也作为上下文的一部分输入模型，或者用它们来增强检索查询（例如，将当前问题+历史记忆中的关键词一起作为检索查询）。