Haystack 集成指南使用 LlamaCppChatGenerator 与 LlamaCppGenerator 在本地运行 GGUF 量化 LLM【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本篇技术指南以 Haystack 官方集成文档 docs-website/reference/integrations-api/llama_cpp.md 为骨架系统讲解llama-cpp-haystack集成中的两个核心组件面向多轮对话的LlamaCppChatGenerator与面向文本补全的LlamaCppGenerator。读者将掌握 GGUF 量化模型的选择与本地部署、model_kwargs/generation_kwargs的完整配置方式、Function Calling工具调用、流式输出、多模态图文推理以及如何在 Haystack Pipeline 中搭建基于本地模型的 RAG 应用。Llama.cpp 集成概述为什么选择 GGUF 量化模型llama.cpp 是一个用 C/C 编写的高效 LLM 推理库其核心价值在于采用量化的GGUF 格式保存模型权重大幅降低内存需求并加速推理。这意味着可以在标准机器上甚至没有 GPU的机器高效运行大型语言模型。在 Haystack 生态中llama-cpp-haystack集成包把 llama.cpp 的能力封装为两个 Haystack 组件源码位于haystack-core-integrations仓库的integrations/llama_cpp目录本文不再展开该外部仓库组件定位输入输出LlamaCppChatGenerator聊天补全Chat CompletionmessagesChatMessage列表或字符串repliesChatMessage列表LlamaCppGenerator文本补全Text Completionprompt字符串replies字符串列表meta元数据列表需要特别说明的是根据 llamacppgenerator.mdx 中的弃用声明LlamaCppGenerator已标记为 deprecated将在未来版本中移除官方建议迁移到LlamaCppChatGenerator后者同样接受纯字符串输入因此本文以LlamaCppChatGenerator为主线展开。两者的工作方式一致GGUF 格式的量化模型二进制文件可从 Hugging Facemodels?librarygguf筛选下载初始化时把本地.gguf文件路径作为model参数传入即可无需联网调用任何外部 API。安装与计算后端选择安装集成包pip install llama-cpp-haystack默认安装行为在 Linux 和 Windows 上为 CPU 构建llama.cpp在 macOS 上使用 Metal。如需其他计算后端如 GPU 加速按以下两步操作先按照 llama-cpp-python 的安装说明为偏好的计算后端安装llama-cpp-python再按上述命令安装llama-cpp-haystack。例如使用cuBLAS 后端NVIDIA GPU 加速的完整命令序列export GGML_CUDA1 CMAKE_ARGS-DGGML_CUDAon pip install llama-cpp-python pip install llama-cpp-haystack文档中的 RAG 示例还会用到sentence-transformers-haystack包提供嵌入组件需一并安装pip install sentence-transformers-haystackLlamaCppChatGenerator 快速上手基本用法from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator from haystack.dataclasses import ChatMessage generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, model_kwargs{n_gpu_layers: -1}, generation_kwargs{max_tokens: 128, temperature: 0.1}, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run(messages)run方法返回字典replies键下是模型生成的ChatMessage列表# {replies: [ChatMessage(contentJohn Cusack, roleChatRole.ASSISTANT: assistant, nameNone, meta{...})} generated_reply result[replies][0].text print(generated_reply)从源码结构看ChatMessage是 Haystack 中统一的多角色消息载体定义见 chat_message.py其ChatRole枚举包含USER、SYSTEM、ASSISTANT、TOOL四种角色对应多轮对话中用户、系统指令、模型回复与工具结果四种消息来源ToolCall数据结构则承载模型发起的工具调用请求。这使得LlamaCppChatGenerator能与 Haystack 生态中其他组件共享同一套消息协议。构造参数详解__init____init__( model: str, n_ctx: int | None 0, n_batch: int | None 512, model_kwargs: dict[str, Any] | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None, streaming_callback: StreamingCallbackT | None None, chat_handler_name: str | None None, model_clip_path: str | None None ) - None各参数说明如下modelstr必填量化文本生成模型的路径例如zephyr-7b-beta.Q4_0.gguf。如果model_kwargs中也指定了模型路径则该参数会被忽略。注意它映射到 llama.cpp 的model_path参数。n_ctxint | None默认0上下文 token 数。设为 0 时从模型自身获取上下文长度。n_batchint | None默认512Prompt 处理的最大批大小。model_kwargsdict[str, Any] | None初始化 LLM 时使用的关键字参数字典提供对模型加载的细粒度控制如n_gpu_layers控制 GPU 层数卸载。当与model、n_ctx、n_batch冲突时此处的 kwargs 优先级更高会覆盖上述三个初始化参数。可用参数详见 llama-cpp-python 的Llama.__init__API 文档。generation_kwargsdict[str, Any] | None定制文本生成的关键字参数字典如max_tokens、temperature、top_k、top_p等。详见 llama-cpp-python 的Llama.create_chat_completionAPI 文档。toolsToolsType | None供模型准备调用的工具可以是Tool和/或Toolset对象的列表也可以是单个Toolset。每个工具的名称必须唯一。ToolsType的类型定义为Sequence[Tool | Toolset] | Toolset见 tool_types.py。streaming_callbackStreamingCallbackT | None收到新 token 时被调用的回调函数。StreamingCallbackT是同步与异步回调的联合类型SyncStreamingCallbackT | AsyncStreamingCallbackT接收StreamingChunk对象定义见 streaming_chunk.py。chat_handler_namestr | None多模态模型的聊天处理器名称常见选项包括Llava16ChatHandler、MoondreamChatHandler、Qwen25VLChatHandler等其余处理器可查阅 llama-cpp-python 的多模态模型文档。model_clip_pathstr | None用于视觉处理的 CLIP 模型路径如mmproj.bin。当提供chat_handler_name时必填。关于模型加载方式有一个重要的底层细节llama.cpp 会自动从模型元数据中提取chat_template来格式化ChatMessage如需覆盖默认模板可以在model_kwargs中传入自定义的chat_handler或chat_format。参数透传的两个层次model、n_ctx、n_batch是为方便使用而暴露的快捷参数model_kwargs和generation_kwargs则是通往 llama.cpp 底层能力的透传通道模型加载层model_kwargs→Llama.__init__包括 GPU 层数n_gpu_layers、chat_format、chat_handler、verbose等。例如把模型全部层卸载到 GPUmodel_kwargs{n_gpu_layers: -1}。生成推理层generation_kwargs→Llama.create_chat_completion包括max_tokens、temperature、top_k、top_p、stop、seed等采样控制参数。注意JSON 模式JSON mode、Function Calling 和 Tools 都可以通过generation_kwargs启用具体用法参考 llama-cpp-python 官方 README 的 JSON/JSON-Schema 模式章节。generation_kwargs的两种传法既可以在初始化时传入作用于每次调用generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, generation_kwargs{max_tokens: 128, temperature: 0.1}, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run(messages)也可以在run调用时动态传入覆盖默认值适用于每次请求参数不同的场景generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run( messages, generation_kwargs{max_tokens: 128, temperature: 0.1}, )run与run_async的签名差异run方法run( messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None, streaming_callback: StreamingCallbackT | None None ) - dict[str, list[ChatMessage]]要点messages可以是ChatMessage列表也可以是纯字符串——字符串会被自动包装成一条user角色的ChatMessage。tools与streaming_callback若在run时传入会覆盖初始化时设置的同名参数。返回{replies: [...]}即模型生成的ChatMessage列表。run_async是run的异步版本签名一致。由于 llama-cpp-python 只提供同步推理接口run_async内部使用线程池thread pool执行推理以避免阻塞事件循环——这是官方 API 文档中明确记载的实现策略也是理解其并发模型的关键它适合在 FastAPI 等异步服务中调用本地模型但真正的计算仍发生在工作线程中。多模态图文推理LLaVA 等LlamaCppChatGenerator原生支持文本 图像的多模态模型。完整示例摘自 llamacppchatgenerator.mdx 与 API 文档from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 初始化多模态支持 generator LlamaCppChatGenerator( modelllava-v1.5-7b-q4_0.gguf, chat_handler_nameLlava15ChatHandler, # 使用 llava-1-5 handler model_clip_pathmmproj-model-f16.gguf, # CLIP 模型 n_ctx4096 # 图像处理需要更大的上下文 ) # 从文件路径创建图像内容 image_content ImageContent.from_file_path(path/to/your/image.jpg) # 构造同时包含文本和图像的多模态消息 messages [ChatMessage.from_user(content_parts[Whats in this image?, image_content])] result generator.run(messages) print(result)多模态输入的底层支撑是 Haystack 的ImageContent数据结构见 image_content.py它以base64 字符串base64_image字段承载图像数据并提供from_file_path、from_bytes、from_base64等构造方法mime_type字段用于标注图像格式如image/png、image/jpeg若不指定则会自动猜测。ChatMessage.from_user(content_parts[...])则把文本与图像对象组合进同一条消息最终由 llama.cpp 的多模态 chat handler 处理。工具调用Function Calling与 ToolsetLlamaCppChatGenerator通过tools参数支持函数调用且工具配置非常灵活支持三种组合方式Tool对象列表逐个传入独立工具单个Toolset直接传入一个完整工具集混合列表在同一列表中组合多个Toolset与独立Tool。示例摘自文档from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 创建独立工具 weather_tool Tool( nameweather, descriptionGet weather info, parameters..., function... ) news_tool Tool( namenews, descriptionGet latest news, parameters..., function... ) # 把相关工具归组为一个 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传递 tools 与 toolsets generator LlamaCppChatGenerator( model/path/to/model.gguf, tools[math_toolset, weather_tool, news_tool], # Toolset 与 Tool 混合 )这样既可以把相关工具组织成逻辑分组也可以按需加入独立工具。更完整的工具使用说明可参考 tool.mdx 与 toolset.mdx。在run调用时还可通过tools参数临时覆盖初始化时设定的工具列表。LlamaCppGenerator文本补全已弃用LlamaCppGenerator提供面向纯文本的补全接口签名与聊天版对应__init__( model: str, n_ctx: int | None 0, n_batch: int | None 512, model_kwargs: dict[str, Any] | None None, generation_kwargs: dict[str, Any] | None None, ) - None run(prompt: str, generation_kwargs: dict[str, Any] | None None)基本用法from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator generator LlamaCppGenerator(modelzephyr-7b-beta.Q4_0.gguf, n_ctx2048, n_batch512) print(generator.run(Who is the best American actor?, generation_kwargs{max_tokens: 128})) # {replies: [John Cusack], meta: [{object: text_completion, ...}]}其返回结构为{replies: [...], meta: [...]}replies是模型生成的字符串列表meta是每条回复对应的元数据字典列表如 token 计数等。注意其generation_kwargs透传到 llama.cpp 的Llama.create_completion补全接口而非聊天接口。弃用提示该组件已标记 deprecated会在未来版本移除请迁移至LlamaCppChatGenerator。序列化to_dict 与 from_dict两个组件都实现了标准序列化协议这是 Haystack 组件可被Pipeline.dumps()/Pipeline.loads()持久化的前提to_dict() - dict[str, Any]把组件序列化为字典包含类型信息与全部构造参数from_dict(data: dict[str, Any]) - LlamaCppChatGenerator从字典反序列化恢复组件实例。序列化机制是 Haystack 核心能力的一部分相关实现可参考 serialization.py 与 deserialization.py。完整实战在 RAG Pipeline 中使用 LlamaCppChatGenerator下面是在检索增强生成RAG流水线中集成LlamaCppChatGenerator的完整示例源自官方文档使用 Simple Wikipedia 数据集与 OpenChat-3.5 模型。第 1 步加载数据集并构造文档# 安装 HuggingFace Datasets 使用 pip install datasets from datasets import load_dataset from haystack import Document, Pipeline from haystack.components.builders.answer_builder import AnswerBuilder from haystack.components.builders import ChatPromptBuilder from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 加载 Simple Wikipedia 数据集前 100 行 dataset load_dataset(pszemraj/simple_wikipedia, splitvalidation[:100]) docs [ Document( contentdoc[text], meta{title: doc[title], url: doc[url]}, ) for doc in dataset ]第 2 步构建索引流水线doc_store InMemoryDocumentStore(embedding_similarity_functioncosine) doc_embedder SentenceTransformersDocumentEmbedder(modelsentence-transformers/all-MiniLM-L6-v2) indexing_pipeline Pipeline() indexing_pipeline.add_component(instancedoc_embedder, nameDocEmbedder) indexing_pipeline.add_component(instanceDocumentWriter(document_storedoc_store), nameDocWriter) indexing_pipeline.connect(DocEmbedder, DocWriter) indexing_pipeline.run({DocEmbedder: {documents: docs}})第 3 步构建 RAG 流水线并接入 LlamaCppChatGeneratorsystem_message ChatMessage.from_system( Answer the question using the provided context. Context: {% for doc in documents %} {{ doc.content }} {% endfor %} , ) user_message ChatMessage.from_user(Question: {{question}}) assistent_message ChatMessage.from_assistant(Answer: ) chat_template [system_message, user_message, assistent_message] rag_pipeline Pipeline() text_embedder SentenceTransformersTextEmbedder(modelsentence-transformers/all-MiniLM-L6-v2) model_path openchat-3.5-1210.Q3_K_S.gguf generator LlamaCppChatGenerator(modelmodel_path, n_ctx4096, n_batch128) rag_pipeline.add_component(instancetext_embedder, nametext_embedder) rag_pipeline.add_component(instanceInMemoryEmbeddingRetriever(document_storedoc_store, top_k3), nameretriever) rag_pipeline.add_component(instanceChatPromptBuilder(templatechat_template), nameprompt_builder) rag_pipeline.add_component(instancegenerator, namellm) rag_pipeline.add_component(instanceAnswerBuilder(), nameanswer_builder) rag_pipeline.connect(text_embedder, retriever) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder, llm) rag_pipeline.connect(llm, answer_builder) rag_pipeline.connect(retriever, answer_builder.documents)第 4 步运行流水线question Which year did the Joker movie release? result rag_pipeline.run( { text_embedder: {text: question}, prompt_builder: {question: question}, llm: {generation_kwargs: {max_tokens: 128, temperature: 0.1}}, answer_builder: {query: question}, }, ) generated_answer result[answer_builder][answers][0] print(generated_answer.data) # The Joker movie was released on October 4, 2019.这一流程展示了LlamaCppChatGenerator在 Pipeline 中的典型位置ChatPromptBuilder之后、AnswerBuilder之前以及在运行时通过run参数逐请求下发generation_kwargs的方式。传统LlamaCppGenerator的 Pipeline 集成方式与之相似区别在于使用PromptBuilder模板含GPT4 Correct User: ... |end_of_turn|等模型专属格式并显式连接llm.replies到answer_builder.replies。组件位置速查与最佳实践根据组件文档中的 key-value 信息表两个组件的关键属性可总结如下属性LlamaCppChatGeneratorLlamaCppGeneratorPipeline 中最常见位置ChatPromptBuilder之后PromptBuilder之后必填初始化参数model模型路径model模型路径必填运行参数messagesChatMessage列表prompt字符串输出变量repliesChatMessage列表replies字符串列表、meta元数据列表包名llama-cpp-haystackllama-cpp-haystack实践建议模型选择在 Hugging Face 按librarygguf筛选下载量化模型文件较小、无需 GPU 的 Q4 量化版本适合开发调试生产环境按显存预算选择更高精度量化。上下文管理多模态或长文档 RAG 场景下需增大n_ctx示例中图像处理用 4096并注意显存/内存占用。参数优先级牢记model_kwargs中的同名参数会覆盖model/n_ctx/n_batch排查参数不生效问题时优先检查这一层。异步集成在异步 Web 服务中调用时使用run_async但需理解其内部通过线程池调度同步推理不会带来真正的并发加速高并发场景需自行管理线程池规模。迁移路径新项目一律使用LlamaCppChatGenerator字符串输入它同样接受因此可无缝替代LlamaCppGenerator。相关仓库资源导航官方集成 API 参考docs-website/reference/integrations-api/llama_cpp.mdChat 版组件使用指南llamacppchatgenerator.mdx补全版组件使用指南llamacppgenerator.mdxChatMessage数据结构源码chat_message.pyImageContent数据结构源码image_content.py流式回调与StreamingChunk定义streaming_chunk.pyToolsType类型定义tool_types.py【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Haystack 集成指南：使用 LlamaCppChatGenerator 与 LlamaCppGenerator 在本地运行 GGUF 量化 LLM
Haystack 集成指南使用 LlamaCppChatGenerator 与 LlamaCppGenerator 在本地运行 GGUF 量化 LLM【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本篇技术指南以 Haystack 官方集成文档 docs-website/reference/integrations-api/llama_cpp.md 为骨架系统讲解llama-cpp-haystack集成中的两个核心组件面向多轮对话的LlamaCppChatGenerator与面向文本补全的LlamaCppGenerator。读者将掌握 GGUF 量化模型的选择与本地部署、model_kwargs/generation_kwargs的完整配置方式、Function Calling工具调用、流式输出、多模态图文推理以及如何在 Haystack Pipeline 中搭建基于本地模型的 RAG 应用。Llama.cpp 集成概述为什么选择 GGUF 量化模型llama.cpp 是一个用 C/C 编写的高效 LLM 推理库其核心价值在于采用量化的GGUF 格式保存模型权重大幅降低内存需求并加速推理。这意味着可以在标准机器上甚至没有 GPU的机器高效运行大型语言模型。在 Haystack 生态中llama-cpp-haystack集成包把 llama.cpp 的能力封装为两个 Haystack 组件源码位于haystack-core-integrations仓库的integrations/llama_cpp目录本文不再展开该外部仓库组件定位输入输出LlamaCppChatGenerator聊天补全Chat CompletionmessagesChatMessage列表或字符串repliesChatMessage列表LlamaCppGenerator文本补全Text Completionprompt字符串replies字符串列表meta元数据列表需要特别说明的是根据 llamacppgenerator.mdx 中的弃用声明LlamaCppGenerator已标记为 deprecated将在未来版本中移除官方建议迁移到LlamaCppChatGenerator后者同样接受纯字符串输入因此本文以LlamaCppChatGenerator为主线展开。两者的工作方式一致GGUF 格式的量化模型二进制文件可从 Hugging Facemodels?librarygguf筛选下载初始化时把本地.gguf文件路径作为model参数传入即可无需联网调用任何外部 API。安装与计算后端选择安装集成包pip install llama-cpp-haystack默认安装行为在 Linux 和 Windows 上为 CPU 构建llama.cpp在 macOS 上使用 Metal。如需其他计算后端如 GPU 加速按以下两步操作先按照 llama-cpp-python 的安装说明为偏好的计算后端安装llama-cpp-python再按上述命令安装llama-cpp-haystack。例如使用cuBLAS 后端NVIDIA GPU 加速的完整命令序列export GGML_CUDA1 CMAKE_ARGS-DGGML_CUDAon pip install llama-cpp-python pip install llama-cpp-haystack文档中的 RAG 示例还会用到sentence-transformers-haystack包提供嵌入组件需一并安装pip install sentence-transformers-haystackLlamaCppChatGenerator 快速上手基本用法from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator from haystack.dataclasses import ChatMessage generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, model_kwargs{n_gpu_layers: -1}, generation_kwargs{max_tokens: 128, temperature: 0.1}, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run(messages)run方法返回字典replies键下是模型生成的ChatMessage列表# {replies: [ChatMessage(contentJohn Cusack, roleChatRole.ASSISTANT: assistant, nameNone, meta{...})} generated_reply result[replies][0].text print(generated_reply)从源码结构看ChatMessage是 Haystack 中统一的多角色消息载体定义见 chat_message.py其ChatRole枚举包含USER、SYSTEM、ASSISTANT、TOOL四种角色对应多轮对话中用户、系统指令、模型回复与工具结果四种消息来源ToolCall数据结构则承载模型发起的工具调用请求。这使得LlamaCppChatGenerator能与 Haystack 生态中其他组件共享同一套消息协议。构造参数详解__init____init__( model: str, n_ctx: int | None 0, n_batch: int | None 512, model_kwargs: dict[str, Any] | None None, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None, streaming_callback: StreamingCallbackT | None None, chat_handler_name: str | None None, model_clip_path: str | None None ) - None各参数说明如下modelstr必填量化文本生成模型的路径例如zephyr-7b-beta.Q4_0.gguf。如果model_kwargs中也指定了模型路径则该参数会被忽略。注意它映射到 llama.cpp 的model_path参数。n_ctxint | None默认0上下文 token 数。设为 0 时从模型自身获取上下文长度。n_batchint | None默认512Prompt 处理的最大批大小。model_kwargsdict[str, Any] | None初始化 LLM 时使用的关键字参数字典提供对模型加载的细粒度控制如n_gpu_layers控制 GPU 层数卸载。当与model、n_ctx、n_batch冲突时此处的 kwargs 优先级更高会覆盖上述三个初始化参数。可用参数详见 llama-cpp-python 的Llama.__init__API 文档。generation_kwargsdict[str, Any] | None定制文本生成的关键字参数字典如max_tokens、temperature、top_k、top_p等。详见 llama-cpp-python 的Llama.create_chat_completionAPI 文档。toolsToolsType | None供模型准备调用的工具可以是Tool和/或Toolset对象的列表也可以是单个Toolset。每个工具的名称必须唯一。ToolsType的类型定义为Sequence[Tool | Toolset] | Toolset见 tool_types.py。streaming_callbackStreamingCallbackT | None收到新 token 时被调用的回调函数。StreamingCallbackT是同步与异步回调的联合类型SyncStreamingCallbackT | AsyncStreamingCallbackT接收StreamingChunk对象定义见 streaming_chunk.py。chat_handler_namestr | None多模态模型的聊天处理器名称常见选项包括Llava16ChatHandler、MoondreamChatHandler、Qwen25VLChatHandler等其余处理器可查阅 llama-cpp-python 的多模态模型文档。model_clip_pathstr | None用于视觉处理的 CLIP 模型路径如mmproj.bin。当提供chat_handler_name时必填。关于模型加载方式有一个重要的底层细节llama.cpp 会自动从模型元数据中提取chat_template来格式化ChatMessage如需覆盖默认模板可以在model_kwargs中传入自定义的chat_handler或chat_format。参数透传的两个层次model、n_ctx、n_batch是为方便使用而暴露的快捷参数model_kwargs和generation_kwargs则是通往 llama.cpp 底层能力的透传通道模型加载层model_kwargs→Llama.__init__包括 GPU 层数n_gpu_layers、chat_format、chat_handler、verbose等。例如把模型全部层卸载到 GPUmodel_kwargs{n_gpu_layers: -1}。生成推理层generation_kwargs→Llama.create_chat_completion包括max_tokens、temperature、top_k、top_p、stop、seed等采样控制参数。注意JSON 模式JSON mode、Function Calling 和 Tools 都可以通过generation_kwargs启用具体用法参考 llama-cpp-python 官方 README 的 JSON/JSON-Schema 模式章节。generation_kwargs的两种传法既可以在初始化时传入作用于每次调用generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, generation_kwargs{max_tokens: 128, temperature: 0.1}, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run(messages)也可以在run调用时动态传入覆盖默认值适用于每次请求参数不同的场景generator LlamaCppChatGenerator( model/content/openchat-3.5-1210.Q3_K_S.gguf, n_ctx512, n_batch128, ) messages [ChatMessage.from_user(Who is the best American actor?)] result generator.run( messages, generation_kwargs{max_tokens: 128, temperature: 0.1}, )run与run_async的签名差异run方法run( messages: list[ChatMessage] | str, generation_kwargs: dict[str, Any] | None None, *, tools: ToolsType | None None, streaming_callback: StreamingCallbackT | None None ) - dict[str, list[ChatMessage]]要点messages可以是ChatMessage列表也可以是纯字符串——字符串会被自动包装成一条user角色的ChatMessage。tools与streaming_callback若在run时传入会覆盖初始化时设置的同名参数。返回{replies: [...]}即模型生成的ChatMessage列表。run_async是run的异步版本签名一致。由于 llama-cpp-python 只提供同步推理接口run_async内部使用线程池thread pool执行推理以避免阻塞事件循环——这是官方 API 文档中明确记载的实现策略也是理解其并发模型的关键它适合在 FastAPI 等异步服务中调用本地模型但真正的计算仍发生在工作线程中。多模态图文推理LLaVA 等LlamaCppChatGenerator原生支持文本 图像的多模态模型。完整示例摘自 llamacppchatgenerator.mdx 与 API 文档from haystack.dataclasses import ChatMessage, ImageContent from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 初始化多模态支持 generator LlamaCppChatGenerator( modelllava-v1.5-7b-q4_0.gguf, chat_handler_nameLlava15ChatHandler, # 使用 llava-1-5 handler model_clip_pathmmproj-model-f16.gguf, # CLIP 模型 n_ctx4096 # 图像处理需要更大的上下文 ) # 从文件路径创建图像内容 image_content ImageContent.from_file_path(path/to/your/image.jpg) # 构造同时包含文本和图像的多模态消息 messages [ChatMessage.from_user(content_parts[Whats in this image?, image_content])] result generator.run(messages) print(result)多模态输入的底层支撑是 Haystack 的ImageContent数据结构见 image_content.py它以base64 字符串base64_image字段承载图像数据并提供from_file_path、from_bytes、from_base64等构造方法mime_type字段用于标注图像格式如image/png、image/jpeg若不指定则会自动猜测。ChatMessage.from_user(content_parts[...])则把文本与图像对象组合进同一条消息最终由 llama.cpp 的多模态 chat handler 处理。工具调用Function Calling与 ToolsetLlamaCppChatGenerator通过tools参数支持函数调用且工具配置非常灵活支持三种组合方式Tool对象列表逐个传入独立工具单个Toolset直接传入一个完整工具集混合列表在同一列表中组合多个Toolset与独立Tool。示例摘自文档from haystack.tools import Tool, Toolset from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 创建独立工具 weather_tool Tool( nameweather, descriptionGet weather info, parameters..., function... ) news_tool Tool( namenews, descriptionGet latest news, parameters..., function... ) # 把相关工具归组为一个 toolset math_toolset Toolset([add_tool, subtract_tool, multiply_tool]) # 混合传递 tools 与 toolsets generator LlamaCppChatGenerator( model/path/to/model.gguf, tools[math_toolset, weather_tool, news_tool], # Toolset 与 Tool 混合 )这样既可以把相关工具组织成逻辑分组也可以按需加入独立工具。更完整的工具使用说明可参考 tool.mdx 与 toolset.mdx。在run调用时还可通过tools参数临时覆盖初始化时设定的工具列表。LlamaCppGenerator文本补全已弃用LlamaCppGenerator提供面向纯文本的补全接口签名与聊天版对应__init__( model: str, n_ctx: int | None 0, n_batch: int | None 512, model_kwargs: dict[str, Any] | None None, generation_kwargs: dict[str, Any] | None None, ) - None run(prompt: str, generation_kwargs: dict[str, Any] | None None)基本用法from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator generator LlamaCppGenerator(modelzephyr-7b-beta.Q4_0.gguf, n_ctx2048, n_batch512) print(generator.run(Who is the best American actor?, generation_kwargs{max_tokens: 128})) # {replies: [John Cusack], meta: [{object: text_completion, ...}]}其返回结构为{replies: [...], meta: [...]}replies是模型生成的字符串列表meta是每条回复对应的元数据字典列表如 token 计数等。注意其generation_kwargs透传到 llama.cpp 的Llama.create_completion补全接口而非聊天接口。弃用提示该组件已标记 deprecated会在未来版本移除请迁移至LlamaCppChatGenerator。序列化to_dict 与 from_dict两个组件都实现了标准序列化协议这是 Haystack 组件可被Pipeline.dumps()/Pipeline.loads()持久化的前提to_dict() - dict[str, Any]把组件序列化为字典包含类型信息与全部构造参数from_dict(data: dict[str, Any]) - LlamaCppChatGenerator从字典反序列化恢复组件实例。序列化机制是 Haystack 核心能力的一部分相关实现可参考 serialization.py 与 deserialization.py。完整实战在 RAG Pipeline 中使用 LlamaCppChatGenerator下面是在检索增强生成RAG流水线中集成LlamaCppChatGenerator的完整示例源自官方文档使用 Simple Wikipedia 数据集与 OpenChat-3.5 模型。第 1 步加载数据集并构造文档# 安装 HuggingFace Datasets 使用 pip install datasets from datasets import load_dataset from haystack import Document, Pipeline from haystack.components.builders.answer_builder import AnswerBuilder from haystack.components.builders import ChatPromptBuilder from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.llama_cpp import LlamaCppChatGenerator # 加载 Simple Wikipedia 数据集前 100 行 dataset load_dataset(pszemraj/simple_wikipedia, splitvalidation[:100]) docs [ Document( contentdoc[text], meta{title: doc[title], url: doc[url]}, ) for doc in dataset ]第 2 步构建索引流水线doc_store InMemoryDocumentStore(embedding_similarity_functioncosine) doc_embedder SentenceTransformersDocumentEmbedder(modelsentence-transformers/all-MiniLM-L6-v2) indexing_pipeline Pipeline() indexing_pipeline.add_component(instancedoc_embedder, nameDocEmbedder) indexing_pipeline.add_component(instanceDocumentWriter(document_storedoc_store), nameDocWriter) indexing_pipeline.connect(DocEmbedder, DocWriter) indexing_pipeline.run({DocEmbedder: {documents: docs}})第 3 步构建 RAG 流水线并接入 LlamaCppChatGeneratorsystem_message ChatMessage.from_system( Answer the question using the provided context. Context: {% for doc in documents %} {{ doc.content }} {% endfor %} , ) user_message ChatMessage.from_user(Question: {{question}}) assistent_message ChatMessage.from_assistant(Answer: ) chat_template [system_message, user_message, assistent_message] rag_pipeline Pipeline() text_embedder SentenceTransformersTextEmbedder(modelsentence-transformers/all-MiniLM-L6-v2) model_path openchat-3.5-1210.Q3_K_S.gguf generator LlamaCppChatGenerator(modelmodel_path, n_ctx4096, n_batch128) rag_pipeline.add_component(instancetext_embedder, nametext_embedder) rag_pipeline.add_component(instanceInMemoryEmbeddingRetriever(document_storedoc_store, top_k3), nameretriever) rag_pipeline.add_component(instanceChatPromptBuilder(templatechat_template), nameprompt_builder) rag_pipeline.add_component(instancegenerator, namellm) rag_pipeline.add_component(instanceAnswerBuilder(), nameanswer_builder) rag_pipeline.connect(text_embedder, retriever) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder, llm) rag_pipeline.connect(llm, answer_builder) rag_pipeline.connect(retriever, answer_builder.documents)第 4 步运行流水线question Which year did the Joker movie release? result rag_pipeline.run( { text_embedder: {text: question}, prompt_builder: {question: question}, llm: {generation_kwargs: {max_tokens: 128, temperature: 0.1}}, answer_builder: {query: question}, }, ) generated_answer result[answer_builder][answers][0] print(generated_answer.data) # The Joker movie was released on October 4, 2019.这一流程展示了LlamaCppChatGenerator在 Pipeline 中的典型位置ChatPromptBuilder之后、AnswerBuilder之前以及在运行时通过run参数逐请求下发generation_kwargs的方式。传统LlamaCppGenerator的 Pipeline 集成方式与之相似区别在于使用PromptBuilder模板含GPT4 Correct User: ... |end_of_turn|等模型专属格式并显式连接llm.replies到answer_builder.replies。组件位置速查与最佳实践根据组件文档中的 key-value 信息表两个组件的关键属性可总结如下属性LlamaCppChatGeneratorLlamaCppGeneratorPipeline 中最常见位置ChatPromptBuilder之后PromptBuilder之后必填初始化参数model模型路径model模型路径必填运行参数messagesChatMessage列表prompt字符串输出变量repliesChatMessage列表replies字符串列表、meta元数据列表包名llama-cpp-haystackllama-cpp-haystack实践建议模型选择在 Hugging Face 按librarygguf筛选下载量化模型文件较小、无需 GPU 的 Q4 量化版本适合开发调试生产环境按显存预算选择更高精度量化。上下文管理多模态或长文档 RAG 场景下需增大n_ctx示例中图像处理用 4096并注意显存/内存占用。参数优先级牢记model_kwargs中的同名参数会覆盖model/n_ctx/n_batch排查参数不生效问题时优先检查这一层。异步集成在异步 Web 服务中调用时使用run_async但需理解其内部通过线程池调度同步推理不会带来真正的并发加速高并发场景需自行管理线程池规模。迁移路径新项目一律使用LlamaCppChatGenerator字符串输入它同样接受因此可无缝替代LlamaCppGenerator。相关仓库资源导航官方集成 API 参考docs-website/reference/integrations-api/llama_cpp.mdChat 版组件使用指南llamacppchatgenerator.mdx补全版组件使用指南llamacppgenerator.mdxChatMessage数据结构源码chat_message.pyImageContent数据结构源码image_content.py流式回调与StreamingChunk定义streaming_chunk.pyToolsType类型定义tool_types.py【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考