MLflow LlamaIndex Flavor 实战指南从索引日志、引擎部署到自动追踪【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本指南围绕 MLflow 开源仓库中mlflow.llama_index模块API 文档入口展开系统讲解 MLflow 如何对 LlamaIndex 的 Index、ChatEngine / QueryEngine / Retriever 以及 Workflow 进行日志记录log、保存save、加载load与自动化追踪autolog tracing。读完本文你将掌握engine_type三种取值的作用与选型、Model-from-Code 模式解决外部向量存储序列化问题、pyfunc 包装器的底层调用机制以及一行代码开启全链路 Tracing 的方法。模块概览mlflow.llama_index提供什么mlflow.llama_index是 MLflow 的官方 LlamaIndex Flavor负责打通两大框架的能力边界LlamaIndex数据驱动的 LLM 应用框架擅长对私域/领域数据建立索引并支撑 RAG、Agent 等应用与MLflow模型追踪、打包、评估与观测平台。其核心价值体现在四个方面Tracking将索引、引擎、Workflow 以及其中的 prompts、LLM、tools、全局配置等作为 MLflow 模型工件artifact管理Model打包索引/引擎/Workflow 及其依赖版本、输入输出接口与元数据保证推理环境跨阶段一致Evaluate借助 MLflow 原生评估能力对 LlamaIndex 模型的推理结果做评测Tracing自动记录 LlamaIndex 内部执行过程实现可观测与快速排障。从 模块入口文件 可以看到该模块对外暴露的完整 API__all__ [autolog, FLAVOR_NAME] # 仅当完整版/skinny 版 MLflow 安装时才暴露模型日志相关 API if not IS_TRACING_SDK_ONLY: from mlflow.llama_index.model import ( _load_pyfunc, load_model, log_model, save_model, ) __all__ [load_model, log_model, save_model, _load_pyfunc]其中FLAVOR_NAME在 constant.py 中定义为字符串常量llama_index它会写入 MLmodel 文件的 flavor 元数据中用于模型加载时识别与分发。注意一个细节load_model、log_model、save_model仅在IS_TRACING_SDK_ONLY为 False即安装了完整版或 skinny 版 MLflow时才会被导入如果只安装了mlflow-tracing独立包则只有autolog与FLAVOR_NAME可用这体现了 MLflow 对轻量级 tracing 场景的模块化设计。mlflow.llama_index模块由以下源码文件构成文件职责model.pysave_model/log_model/load_model/_load_pyfunc核心实现pyfunc_wrapper.py将 LlamaIndex 对象包装为 MLflow pyfunc 模型的四种包装器serialize_objects.py全局Settings对象的序列化与反序列化autolog.pyautolog自动追踪入口tracer.pyLlamaIndex 事件/跨度Span到 MLflow Trace 的桥接实现constant.pyFLAVOR_NAME常量支持的模型类型Index、Engine、Workflow不是任何 LlamaIndex 对象都能被该 Flavor 保存。model.py 中_supported_classes()明确定义了受支持的类型集合BaseIndex索引对象如VectorStoreIndexBaseChatEngine聊天引擎保持对话历史BaseQueryEngine查询引擎单轮问答BaseRetriever检索器返回 top-k 相关文档WorkflowLlamaIndex 的事件驱动编排框架 0.11.0 可用。校验逻辑位于_validate_and_prepare_llama_index_model_or_pathmodel.py当传入对象不属于上述任何基类时会抛出MlflowException.invalid_parameter_value并列出受支持的类名清单。非 Index 对象Engine、Workflow只能通过 Model-from-Code 模式保存直接传对象实例会被拒绝——这一点在save_model的attention提示和 model.py 的异常分支中均有明确体现。Workflow 的特殊性Workflow 是 LlamaIndex 新一代的 Agent 编排框架用于构建 Agent、RAG 流程、数据抽取流水线等任意 LLM 应用。在 pyfunc_wrapper.py 中WorkflowWrapper是一个独立实现它没有index属性Workflow 没有索引也没有engine_type其predict通过asyncio驱动workflow.run(**input)并把结果统一封装为列表返回。由于 MLflow pyfunc 暂不支持异步推理Workflow 的predict是同步阻塞的——源码中专门实现了_wait_async_task来处理已有事件循环运行如 Notebook、pytest-asyncio 环境的情况此时会新起一个线程运行独立事件循环避免使用nest_asyncio注释说明其会破坏 OpenAI 异步客户端。核心 API 之一save_model 与 log_modelsave_model将 LlamaIndex 模型保存到本地文件系统log_model则在当前 MLflow run 下将其记录为工件artifact。两者共享同一套参数体系下面结合 model.py 中的 docstring 与实现逐一说明。参数详解参数类型说明llama_index_model对象或 str受支持的 LlamaIndex 对象Index / Engine / Workflow或包含模型定义脚本的路径字符串path仅 save_modelstr本地保存目录序列化模型以 YAML 形式落盘artifact_path/name仅 log_modelstrname为工件名artifact_path已废弃engine_typestr保存 Index 对象时必填决定加载为 pyfunc 后的推理接口对非 Index 对象传入会被忽略源码中会打印 warning见 model.pymodel_configdict 或 str加载模型时应用的配置按模型类型与保存方式不同而有差异见下文signatureModelSignature输入输出 Schema可用mlflow.models.infer_signature推断显式传False可跳过推断input_exampleModelInputExample示例输入配合signatureNone时自动推断模型签名pip_requirements/extra_pip_requirementslist 或 str依赖管理默认使用get_default_pip_requirements()即钉住版本的llama-index见 model.pyconda_envdict自定义 Conda 环境metadatadict附加元数据registered_model_namestr注册模型版本仅 log_modelawait_registration_forint等待模型版本进入 READY 状态秒数默认 5 分钟0 或 None 跳过等待prompts/params/tags/model_type/step/model_id多样log_model新增的统一参数透传给mlflow.models.Model.loglog_model的底层实现非常简洁——它直接委托给mlflow.models.Model.log(...)model.py将上述参数以flavormlflow.llama_index的方式透传从而复用 MLflow 统一的模型注册、提示prompt管理与参数管理能力。engine_type三种引擎接口的选型engine_type是保存 Index 时最重要的参数。它不改变索引本身只决定加载回索引后以哪种引擎接口对外推理。源码 pyfunc_wrapper.py 中的_create_wrapper_from_index揭示了其底层行为——本质上是对索引调用对应的方法engine_type底层调用包装器类推理语义chatindex.as_chat_engine(**model_config)ChatEngineWrapper会话式对话保持对话历史queryindex.as_query_engine(**model_config)QueryEngineWrapper单查询返回响应retrieverindex.as_retriever(**model_config)RetrieverEngineWrapper返回 top-k 相关文档节点若engine_type不在SUPPORTED_ENGINES {chat, query, retriever}内_validate_engine_typemodel.py会抛出ValueError并提示受支持的取值。三种包装器的_predict_single分别调用engine.chat(...).response、engine.query(...).response、engine.retrieve(...)其中 Retriever 返回的是NodeWithScore的字典列表每个节点经node.dict()转换。model_config 的两种应用方式model_config的语义取决于模型类型与保存方式model.py 有完整示例方式一直接保存内存 Index 对象。此时model_config会作为关键字参数传给as_chat_engine()/as_query_engine()/as_retriever()用于在日志记录时实例化引擎with mlflow.start_run(): model_info mlflow.llama_index.log_model( index, nameindex, engine_typechat, model_config{top_k: 10}, ) # 加载时 MLflow 实际执行 index.as_chat_engine(top_k10) engine mlflow.pyfunc.load_model(model_info.model_uri)方式二Model-from-Code 模式。此时配置通过mlflow.models.ModelConfig单例在模型代码中访问适合需要注入外部向量存储地址等运行环境参数的情形with mlflow.start_run(): model_info mlflow.llama_index.log_model( model.py, namemodel, model_config{qdrant_host: localhost, qdrant_port: 6333}, )# model.py 内部 import mlflow model_config mlflow.models.ModelConfig() qdrant_host model_config.get(qdrant_host, localhost) qdrant_port model_config.get(qdrant_port, 6333) client qdrant_client.Client(hostqdrant_host, portqdrant_port)Settings 序列化全局配置如何随模型一起保存LlamaIndex 的全局Settings单例管理着整个应用的 LLM、Embedding、CallbackManager 等共享资源。save_model在保存时调用serialize_settings(settings_path)model.py把 Settings 快照写入模型目录下的settings.json从而保证推理时复现与日志记录时一致的运行环境。serialize_objects.py 的serialize_settings实现了两个关键策略API Key 脱敏_sanitize_api_key会剔除所有键名包含api_key的字段避免密钥泄漏。因此推理时必须通过环境变量等方式重新注入 API Key——该行为在保存时会有明确日志提示。可序列化白名单只有继承自llama_index.core.schema.BaseComponent的对象才能被序列化转为{object_constructor: 导入路径, object_kwargs: 参数字典}结构不可序列化的对象如函数对象会被记录到 unsupported 列表并打印警告不会随模型保存。序列化过程中还包含一些细节处理空的CallbackManager被跳过callable 字段被排除PromptTemplate的template_vars需要特殊构造_construct_prompt_template_object对于 Embedding 模型当model与model_name参数相同时会去重避免构造时重复传参。加载侧由load_model中的deserialize_settingsmodel.py还原它通过属性 setter 把各字段写回全局Settings单例——这意味着加载模型会改变进程内的全局 Settings在 官方 Flavor 文档 中可以看到切换 LLM 的用法加载后直接修改Settings.llm即可为后续推理更换模型。核心 API 之二load_model 与 pyfunc 加载mlflow.llama_index.load_model加载原生对象load_model(model_uri, dst_pathNone)model.py将模型加载为 LlamaIndex 原生对象Index / Engine / Workflow支持多种 URI 形式本地路径/Users/me/path/to/local/model或相对路径对象存储s3://my_bucket/path/to/modelMLflow 运行工件runs:/mlflow_run_id/run-relative/path/to/model工件服务mlflow-artifacts:/path/to/model加载流程源码可验证下载工件 → 读取 MLmodel 文件 → 反序列化settings.json→ 调用_load_llama_model加载索引本体。_load_llama_modelmodel.py会优先检查 pyfunc flavor 配置中是否存在model_code_path若存在Model-from-Code 模式则执行模型脚本重建对象否则从index/目录通过StorageContext.from_defaults(persist_dir...)load_index_from_storage恢复序列化索引。_save_indexmodel.py在保存侧通过index.storage_context.persist()完成落盘。mlflow.pyfunc.load_model加载推理模型当需要标准推理接口部署、评估时使用mlflow.pyfunc.load_model。它返回一个 pyfunc 模型由_load_pyfuncmodel.py驱动先调用load_model拿到原生对象再从 flavor 配置中取出engine_type最后由create_pyfunc_wrapperpyfunc_wrapper.py工厂函数根据对象类型分发if isinstance(model, Workflow): # 优先判断 Workflow return WorkflowWrapper(model, model_config) if isinstance(model, BaseIndex): # Index → 按 engine_type 构建引擎 return _create_wrapper_from_index(model, engine_type, model_config) else: # 其余按 Engine 处理无公共基类 return _create_wrapper_from_engine(model, model_config)输入处理差异是四种包装器的核心区别QueryEngine / Retriever输入被转换为QueryBundle支持 str、dict、list 及 pandas 单行解包见_format_predict_input_query_engine_and_retrieverpyfunc_wrapper.pyChatEngine额外支持chat_history参数且会自动把 dict 列表转换为 LlamaIndexChatMessage对象_convert_chat_message_history_to_chat_message_objectspyfunc_wrapper.pyWorkflow输入必须是 dict会与params合并且每个输入被包装为{input: ...}形式调用workflow.run(**x)。所有包装器都支持批处理predict遇到 list 输入时逐条执行_do_inference并返回结果列表。get_raw_model()可用于获取底层 LlamaIndex 原生对象。autolog一行代码开启全链路 Tracingmlflow.llama_index.autolog(log_tracesTrue, disableFalse, silentFalse)autolog.py是 MLflow 为 LlamaIndex 提供的自动追踪入口当前仅支持追踪tracing模型与工件的自动日志尚未实现源码中_autolog内部标注了TODO: Implement patching logic for autologging models and artifacts。import mlflow mlflow.llama_index.autolog() # 开启追踪 # ... 执行 LlamaIndex 引擎/Workflow 调用 ... mlflow.llama_index.autolog(disableTrue) # 关闭追踪三个参数的含义参数默认值说明log_tracesTrue是否记录 LlamaIndex 推理过程中的 tracesdisableFalseTrue时禁用并清理该集成silentFalse是否抑制 MLflow 的事件日志与警告实现上autolog在启用时调用set_llama_index_tracer()向 LlamaIndex 全局 dispatcher 注册两个处理器tracer.pyMlflowSpanHandler继承BaseSpanHandler负责 LlamaIndex span 的生命周期管理把每个 span 映射为 MLflow 的LiveSpannew_span/prepare_to_exit_span/prepare_to_drop_spanMlflowEventHandler继承BaseEventHandler作为补充元数据来源处理 LLM 调用开始/结束、Embedding 开始、Agent 工具调用、ReRank、异常等事件将 model_name、prompt 模板、token 用量等写入 span 属性。值得关注的是 span 类型映射逻辑_get_span_typetracer.pyBaseLLM/MultiModalLLM→LLMBaseRetriever→RETRIEVERAgent →AGENTBaseEmbedding→EMBEDDINGBaseTool→TOOL其余归为CHAIN。这为 RAG 链路提供了精细的可观测粒度一次查询会被拆解为检索retriever、embedding、LLM 调用等多个 span。此外源码还处理了三个进阶场景流式响应StreamResolvertracer.py负责在流式 generator 耗尽时关闭对应 span并递归关闭共享同一 token 流的父 span避免 trace 一直停留在 IN_PROGRESS 状态Token 用量从 LLM 响应的raw.usage或additional_kwargs中提取 prompt/completion/total tokens换算为SpanAttributeKey.CHAT_USAGE标准属性tracer.py供 MLflow 的 Token 用量与成本看板统计Workflow 兼容针对llama-index-workflows 2.0返回WorkflowHandler的同步调用方式span 会保持打开直到收到StopEvent才关闭_pending_workflow_span_ids机制tracer.py。在 Tracing 集成文档 中可以看到完整的入门示例下载示例数据 → 构建VectorStoreIndex→ 调用mlflow.llama_index.autolog()→ 查询索引随后即可在 MLflow UI 的 Traces 标签页查看每次预测的完整执行链路。注意官方文档也明确提示追踪支持异步预测与流式响应但不支持两者组合如astream_chat。实战示例完整的索引日志与推理流程结合 官方 Flavor 文档 与源码一个最简但完整的端到端流程如下1. 构建索引from llama_index.core import VectorStoreIndex, SimpleDirectoryReader documents SimpleDirectoryReader(data).load_data() index VectorStoreIndex.from_documents(documents)2. 记录到 MLflow 并加载推理import mlflow mlflow.set_experiment(llama-index-demo) with mlflow.start_run(): model_info mlflow.llama_index.log_model( index, nameindex, engine_typechat, input_exampleWhat did the author do growing up?, ) # 以 pyfunc 模型加载chat 引擎 model mlflow.pyfunc.load_model(model_info.model_uri) response model.predict(What was the first program the author wrote?) print(response) # chat 引擎会保留对话历史 response model.predict(How did the author feel about it?) # 需要原生对象时用 load_model index_loaded mlflow.llama_index.load_model(model_info.model_uri)这里有一个官方 FAQ 中的实用技巧已经以 query 引擎类型记录的索引无需重建即可切换为 chat 引擎——只需mlflow.llama_index.load_model加载回索引再以新的engine_typechat重新log_model即可或者直接在原生索引上调用index.as_chat_engine().chat(...)等原生 API。3. 外部向量存储使用 Model-from-Code默认的SimpleVectorStore将文档嵌入保存在内存中可以被直接序列化。但使用QdrantVectorStore、DatabricksVectorSearch等外部向量存储时索引数据位于远程、不支持本地序列化直接传对象会失败。此时应把索引定义写入独立 Python 文件并在文件末尾调用mlflow.models.set_model(index)# %%writefile index.py import qdrant_client from llama_index.core import VectorStoreIndex from llama_index.vector_stores.qdrant import QdrantVectorStore client qdrant_client.QdrantClient(hostlocalhost, port6333) vector_store QdrantVectorStore(clientclient, collection_namemy_collection) index VectorStoreIndex.from_vector_store(vector_storevector_store) # 关键告诉 MLflow 记录该索引 mlflow.models.set_model(index)然后传路径给log_modelwith mlflow.start_run(): model_info mlflow.llama_index.log_model( index.py, nameindex, engine_typequery, model_config{qdrant_host: localhost, qdrant_port: 6333}, )Workflow 的日志与加载方式与之类似官方文档with mlflow.start_run(): model_info mlflow.llama_index.log_model( /path/to/workflow.py, namemodel, input_example{input: What is MLflow?}, ) workflow mlflow.llama_index.load_model(model_info.model_uri) await workflow.run(inputWhat is MLflow?) # 原生异步调用 pyfunc_model mlflow.pyfunc.load_model(model_info.model_uri) pyfunc_model.predict({input: What is MLflow?}) # 同步阻塞调用测试验证与进一步探索mlflow.llama_index模块在 tests/llama_index 下拥有完善的测试覆盖可以作为理解各能力边界的权威参考test_llama_index_model_export.py验证save_model/log_model/load_model的完整往返流程包括 Index、Engine、Workflow 与 Model-from-Code 场景test_llama_index_pyfunc_wrapper.py验证四种包装器的输入转换、批处理与engine_type分发逻辑test_llama_index_serialization.py验证 Settings 序列化往返、API Key 脱敏与不可序列化对象告警test_llama_index_autolog.py 与 test_llama_index_tracer.py验证 autolog 启用/禁用、span 类型映射、流式响应解析与 token 用量统计test_llama_index_evaluate.py验证mlflow.evaluate与 LlamaIndex pyfunc 模型的配合输入解包inputs列的逻辑在 pyfunc_wrapper.py 中有专门处理。官方文档还提供了两个渐进式入门教程供深入学习详见 docs/docs/genai/flavors/llama-indexllama_index_quickstart.ipynb最简 VectorStoreIndex 配置与llama_index_workflow_tutorial.ipynb构建并追踪简单的 Agentic Workflow。此外仓库中的示例代码 examples/llama_index/autolog.py 与 examples/llama_index/simple_index.py 提供了可立即运行的最小演示。总结mlflow.llama_index是 MLflow 与 LlamaIndex 之间完整的工程化桥梁通过log_model/save_model把 Index、Engine、Workflow 连同依赖环境与全局 Settings 一起打包进 MLflow 模型工件借助engine_type在加载时灵活切换 chat / query / retriever 三种推理接口通过 Model-from-Code 模式突破外部向量存储的序列化限制并由autolog一行代码获得覆盖检索、嵌入、LLM 调用全链路的自动追踪与 Token 成本观测。无论是构建 RAG 应用、Agent 编排还是将其部署到生产推理端点该 Flavor 都能让 LlamaIndex 应用获得与 MLflow 生态一致的模型管理、评估与可观测能力。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考