LlamaIndex 系列【5】智能体开发：大语言模型接入与基础调用

文章目录前言1. 构建智能体大模型应用的关键步骤1.1 大模型基础调用能力1.2 构建智能体1.3 工作流Workflows开发1.4 智能体 RAG 能力集成1.5 业务落地1.6 链路追踪与调试1.7 效果评估2. 使用大模型阿里云百炼2.1 统一 LLM 抽象2.2 先理解OpenAILike 是什么2.3 基础文本补全2.4 流式输出2.5 对话接口2.5.1 基础对话调用2.5.2 同步流式对话2.5.3 异步流式对话2.6 指定模型名称2.7 多模态大模型调用2.8 模型工具调用Function Calling2.9 接入本地大模型Ollama前言LlamaIndex为大模型应用开发提供了从基础模型调用、RAG知识库搭建、智能体开发到高阶工作流定制、落地优化的全链路解决方案模块化、标准化的开发模式极大降低了企业级AI应用的开发门槛。后续我们将从大模型基础调用开始循序渐进拆解每一个核心功能的开发逻辑、实操方法与优化技巧带大家从零完成完整的大模型智能应用开发落地。1. 构建智能体大模型应用的关键步骤基于LlamaIndex开发智能体大模型应用拥有标准化、模块化的开发流程。1.1 大模型基础调用能力大模型调用是所有AI应用开发的基础。LlamaIndex提供统一的调用接口兼容市面上数十种主流大模型。支持两种部署调用模式既可以调用云端远程API服务快速开发也支持本地私有化部署模型适配不同场景的算力、隐私、成本需求帮助开发者快速完成大模型能力接入。1.2 构建智能体智能体是由大模型驱动的自动化执行单元核心能力是依托各类工具与外部环境交互不仅能完成信息检索还可自主执行各类业务动作是复杂AI应用的核心载体。本模块核心开发内容包含基础单智能体搭建从零构建轻量化智能体配置基础工具实现与外部场景的基础交互能力。预制工具快速复用依托官方LlamaHub资源库直接调用海量成熟预制工具无需重复开发大幅提升开发效率。状态持久化维护支持智能体运行状态保存与迭代满足复杂、多轮、长链路的业务场景需求。流式事件输出提供实时流式输出能力展示任务执行过程为用户提供可视化反馈优化交互体验。人在回路机制支持人工介入反馈与校正有效规避智能体自主执行的偏差保障业务准确性。多智能体协同系统基于AgentWorkflow搭建多智能体架构实现多角色智能体分工协作支撑超复杂业务系统落地。1.3 工作流Workflows开发工作流是LlamaIndex高阶智能体应用的底层核心架构属于事件驱动的轻量化抽象层是开发定制化、高阶智能应用的基础。开发者可基于高层封装快速开发也可从零完全自定义业务逻辑核心能力包含搭建基础工作流快速实现简易智能体业务逻辑支持循环、分支等核心控制流组合搭建复杂业务逻辑任务并发执行高效拆分并行任务提升整体运行效率支持流式事件推送同步展示任务执行状态具备状态持久化能力适配长周期、复杂业务场景完善的可观测能力可对接各类链路追踪组件实现应用调试、故障排查。1.4 智能体 RAG 能力集成RAG检索增强生成是打通私有数据与大模型的核心技术解决了大模型知识滞后、私有场景适配性差的问题是智能体具备专业知识库问答能力的关键。完整的RAG流水线开发包含七大核心环节多源数据接入依托LlamaHub数百种专属连接器兼容文本、PDF、数据库、第三方API等全类型数据源实现异构数据统一接入。索引构建与向量化通过多样化数据组织策略对原始数据进行切分、向量化处理生成语义向量保障检索上下文的精准度。结构化数据存储将向量数据、文档摘要、元数据统一存入向量数据库实现数据持久化降低重复计算成本提升访问效率。智能检索优化匹配多样化索引查询策略从检索速度、相关性、准确率多维度优化同时支持输出标准化结构化数据。1.5 业务落地适配智能问答、聊天机器人、API服务、自主智能体等多类应用场景支持项目产业化部署。1.6 链路追踪与调试依托可观测能力洞察应用内部运行逻辑快速定位检索、生成环节的故障与问题。。1.7 效果评估任何方案都存在优劣取舍。应用开发、上线、迭代流程中需要持续评估改动是否在准确率、性能、表达效果、成本等维度带来正向提升。可靠的效果评估是LLM应用开发不可或缺的一环。2. 使用大模型阿里云百炼2.1 统一 LLM 抽象在构建基于私有数据的大模型应用时首要环节就是接入大语言模型。但这里有一个很现实的问题不同厂商的API风格各不相同OpenAI用chat.completions通义千问有自己的SDK调用方式Ollama是本地HTTP接口Gemini又是另一套协议。如果直接在业务代码里对接各家SDK你很快会陷入大量重复的适配代码中参数格式不一样、流式响应不一样、错误处理不一样、异步支持也不一样。LlamaIndex的解法是设计一套统一 LLM 抽象接口把调用一个大模型这件事抽象成complete()/chat()/stream_*()等几个标准方法你写的业务代码只面向这套接口。切换模型厂商时只需要换一个类、改几个参数其余代码一概不动你的业务代码 │ 只依赖统一抽象 ▼ ┌─────────────────────────────────────────┐ │ BaseLLM统一接口 │ │ complete/chat/stream/acomplete...│ └─────────────────────────────────────────┘ │ 按厂商实现 ├──────► OpenAI llama-index-llms-openai ├──────► OpenAILike llama-index-llms-openai-like兼容协议服务 ├──────► Ollama llama-index-llms-ollama本地模型 ├──────► DashScope 通义千问原生集成 └──────► 自定义 继承 CustomLLM 自行实现2.2 先理解OpenAILike 是什么在动手写代码之前先讲清楚一个概念OpenAI 兼容协议。OpenAI定义了一套事实标准的HTTP API形态/chat/completions、/embeddings、/models等端点 JSON请求/响应格式。很多厂商为了让生态成熟的开源工具能直接接入自己会提供兼容OpenAI 协议的端点。阿里云百炼就是这样它在自己的大模型服务上包了一层与OpenAI完全一致的接口。所以LlamaIndex接入百炼不需要百炼专属集成包而是用openai-like这个万能适配器pip install llama-index-llms-openai-like它的核心类是OpenAILike。注意类名后面的Like——它继承自 OpenAI 类只是把OpenAI类里硬编码的官方地址和模型假设放开让你可以自由指定api_base端点地址和模型名。安装后在项目根目录创建.env文件写入你的密钥在百炼控制台创建API-KEYDASHSCOPE_API_KEYsk-xxx.env是社区通用的本地配置约定配合python-dotenv库加载避免把密钥写进代码、避免泄露到Git仓库。配套代码里的config.py已内置load_dotenv()。2.3 基础文本补全complete()的语义是给模型一句话让它接着往下写文本补全适合续写、翻译、摘要等一次性生成场景importosfromllama_index.llms.openai_likeimportOpenAILike llmOpenAILike(modelqwen-plus,api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,# qwen 均为 chat 模型必须开启is_function_calling_modelTrue,# qwen-plus 支持工具调用必须显式声明)responsellm.complete(William Shakespeare is )print(response)逐行解读model指定模型版本。qwen-plus是百炼的通用主力模型性价比与能力平衡api_key/api_base从环境变量读密钥api_base指向百炼的OpenAI兼容端点整个兼容模式的关键就这两个参数is_chat_modelTrue告诉LlamaIndex这是对话式模型。qwen系列只提供chat接口没有传统的completion接口complete()内部会自动包装成一次单轮对话。如果这里不设True框架会尝试走旧的补全接口行为异常is_function_calling_modelTrue声明模型支持工具调用。这个开关第6节会用到建议与is_chat_model一起写上一步到位。预期输出qwen-plus实测William Shakespeare was an English playwright, poet, and actor, widely regarded as one of the greatest writers in the English language...配套异步版本acomplete()2.4 流式输出上一节的complete()是等全部生成完一次性返回。但在很多场景下我们希望边生成边显示聊天机器人逐字输出的打字机效果、长文档生成的进度反馈都是流式输出。原理模型实际是逐个token词元生成的。流式接口把这一过程摊开——服务端每生成一个token就推送一次客户端收到的是增量delta而不是等完整的答案importosfromllama_index.llms.openai_likeimportOpenAILike llmOpenAILike(modelqwen-plus,api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,is_function_calling_modelTrue,)handlellm.stream_complete(William Shakespeare is )fortokeninhandle:print(token.delta,end,flushTrue)代码里有两个细节值得注意token.delta是本次收到的增量文本end表示不换行让所有增量拼成一句话flushTrue强制立即刷新标准输出否则Python会缓冲输出在终端里就看不到逐字效果了。配套异步版本astream_complete()。LlamaIndex为海量大模型提供统一调用接口。使用新模型往往只需要安装对应集成包pipinstallllama-index-llms-openai一行代码即可完成调用fromllama_index.llms.openaiimportOpenAI responseOpenAI().complete(William Shakespeare is )print(response)注意环境变量需要配置OPENAI_API_KEY更多细节参考入门教程。complete也提供异步版本acomplete。调用stream_complete获取流式返回返回生成器逐token输出内容handleOpenAI().stream_complete(William Shakespeare is )fortokeninhandle:print(token.delta,end,flushTrue)stream_complete的异步版本为astream_complete。2.5 对话接口如果说complete()是一句话接龙chat()就是真正的对话。对话场景需要区分谁在说话系统设定、用户消息、助手回复。LlamaIndex用ChatMessage结构表达这一点fromllama_index.core.llmsimportChatMessage messages[ChatMessage(rolesystem,contentYou are a helpful assistant.),# 系统角色设定人设与规则ChatMessage(roleuser,contentTell me a joke.),# 用户角色本轮提问]消息列表是累积的——多轮对话就是把每一轮的问答都追加进列表模型才能记住上下文。2.5.1 基础对话调用importosfromllama_index.core.llmsimportChatMessagefromllama_index.llms.openai_likeimportOpenAILike messages[ChatMessage(rolesystem,contentYou are a helpful assistant.),ChatMessage(roleuser,contentTell me a joke.),]llmOpenAILike(modelqwen-plus,api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,is_function_calling_modelTrue,)chat_responsellm.chat(messages)print(chat_response.message.content)返回对象是ChatResponsechat_response.message.content才是助手回复的文本。预期输出Why dont scientists trust atoms? Because they make up everything.2.5.2 同步流式对话普通脚本 /Jupyter Notebook场景希望看到逐字输出stream_responsellm.stream_chat(messages)fortokeninstream_response:print(token.delta,end,flushTrue)2.5.3 异步流式对话Web服务场景FastAPI等异步框架的标准姿势异步 流式组合既不阻塞事件循环又能边生成边推送给前端stream_responseawaitllm.astream_chat(messages)asyncfortokeninstream_response:print(token.delta,end,flushTrue)为什么推荐异步异步接口把等待网络响应的时间让出来同一进程可以并发处理成百上千个请求。LlamaIndex的agent如FunctionAgent内部也是异步驱动的官方推荐使用异步写法。记住一条规律同步版用于脚本/调试异步版用于服务。2.6 指定模型名称同一个厂商有多个模型版本能力、速度、价格各不相同。通过model参数指定importosfromllama_index.llms.openai_likeimportOpenAILike llmOpenAILike(modelqwen-plus,# 通用主力qwen-plus / qwen-max / qwen-turboapi_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,is_function_calling_modelTrue,)responsellm.complete(Who is Laurie Voss?)print(response)2.7 多模态大模型调用文本之外很多任务需要看图说话图片理解、截图分析、文档OCR。LlamaIndex的blocks机制把多模态消息表达为内容块列表——一条消息可以同时包含图片块和文本块importosfromllama_index.core.llmsimportChatMessage,TextBlock,ImageBlockfromllama_index.llms.openai_likeimportOpenAILike llmOpenAILike(modelqwen-vl-max,# 百炼视觉理解模型api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,is_function_calling_modelTrue,)messages[ChatMessage(roleuser,blocks[ImageBlock(pathimage.png),# 图片块从本地路径加载TextBlock(textDescribe the image in a few sentences.),# 文本块指令],)]respllm.chat(messages)print(resp.message.content)注意多模态模型的is_chat_model同样要设为TrueImageBlock(path...)支持本地路径也可以传base64数据ImageBlock(image_base64...)或URL。预期输出实测用一张蓝底白字的测试图The image displays a plain, light blue background with a single line of black text positioned in the upper-left corner. The text reads: Hello LlamaIndex Qwen VL...如果想做图文 RAG文本搜图、以图搜图、图文混合问答单靠llm.chat不够——LlamaIndex还提供了独立的MultiModalLLM抽象配合多模态向量索引使用。当前主流支持GPT-4V、Gemini、LLaVa、Qwen-VL、CogVLM等。注意框架对音频、视频的端到端RAG尚不完善目前多模态RAG主要支持图片模态。2.8 模型工具调用Function Calling这是让LLM从聊天机器人升级为智能体的关键能力。先讲原理——Function Calling 是一个四步循环① 工具注册把你的 Python 函数转成 JSON Schema参数名、类型、描述 │ ▼ ② 模型决策LLM 分析用户问题决定该调用哪个函数、填什么参数│ ▼ ③ 框架执行按模型给出的参数调用你的函数拿到真实结果 │ ▼ ④ 结果回填把函数结果作为消息喂回 LLM让它基于结果生成最终回答关键在于第 ② 步——选择权在模型。你的代码不需要写如果用户问XX就调YY的规则模型根据函数描述自主判断。LlamaIndex用predict_and_call把整个四步循环封装成一次调用importosfromllama_index.core.toolsimportFunctionToolfromllama_index.llms.openai_likeimportOpenAILikedefgenerate_song(name:str,artist:str)-dict:Generates a song with provided name and artist.return{name:name,artist:artist}toolFunctionTool.from_defaults(fngenerate_song)llmOpenAILike(modelqwen-plus,api_keyos.environ[DASHSCOPE_API_KEY],api_basehttps://dashscope.aliyuncs.com/compatible-mode/v1,is_chat_modelTrue,is_function_calling_modelTrue,# ← 工具调用必须为 True否则报 ValueError)responsellm.predict_and_call([tool],Pick a random song for me,)print(str(response))关键点解读FunctionTool.from_defaults(fn...)框架会自动解析函数签名和 docstring生成工具schema——函数名、参数类型、默认值、描述都来自你的代码本身无需手写JSON。predict_and_call([tool], prompt)第一个参数是工具列表第二个参数是用户请求模型自主决定是否调用、调用哪个、填什么参数预期输出实测模型随机选了一首歌并正确填入了两个参数{name: Here Comes the Sun, artist: The Beatles}该接口兼容所有支持函数调用的大模型。工具与智能体的进阶用法FunctionAgent、AgentWorkflow——让模型自主决定何时调工具、调几次、如何综合结果是另一篇教程的内容。2.9 接入本地大模型Ollama前面几节都是云端API。有些场景你希望模型数据不出内网私有数据合规、离线环境、控制成本。Ollama是当前最流行的本地模型运行时LlamaIndex通过llama-index-llms-ollama集成fromllama_index.llms.ollamaimportOllama llmOllama(modelllama3.3,request_timeout60.0,context_window8000,# 限制上下文窗口控制内存占用)切换成本几乎为零——这是统一抽象最大的价值第2~6节的代码只要把OpenAILike(...)换成Ollama(...)其余逻辑complete/chat/流式/异步完全不用改。两个参数的含义request_timeout本地模型生成长文本可能较慢放宽超时避免误报context_window按你的显存限制上下文窗口防止内存溢出。本地部署前先ollama pull llama3.3拉取模型本地模型是否支持工具调用取决于模型本身。