1. 项目概述与集成动机这次项目要把Azure OpenAI与LlamaIndex集成起来做一个内部运维文档问答案例项目代号是Basic/customization5。Basic的意思很简单就是先把最基础的链路跑通读取一批本地文档、建立索引、用Azure OpenAI回答用户问题customization5则是预留了后续扩展点比如改提示词、换数据源、加多轮对话等。整套方案适合刚接触Azure OpenAI或者想把LlamaIndex真正落地到业务里的开发者看完可以直接照着搭一套最小可用系统。我自己之前也试过直接用OpenAI的API做问答但到了企业内部场景数据安全和运维管理的要求会高很多。Azure OpenAI的好处是有统一的资源管理、密钥轮换、配额监控而且模型以托管方式提供不用自己管GPU集群。LlamaIndex则负责把私人文档变成可检索的知识库省去了大量手工编写文本切分和向量检索逻辑的工作。把这两者凑到一起一个基本的RAG检索增强生成应用就成型了。1.1 为什么把Azure OpenAI和LlamaIndex放一起很多人第一次接触LlamaIndex容易把它当成一个“调用LLM的封装库”。确实它支持很多LLM但核心价值在于索引和检索。它能把PDF、Markdown、Word、TXT等文档切分成节点对节点做Embedding然后存入向量索引。用户提问时它先召回最相关的几个文本片段再把片段塞给LLM生成最终答案。这种架构就是RAG能有效减少模型乱编也能在回答里附上可追溯的来源。而Azure OpenAI在这个链路里承担了两个角色一个是生成回答的LLM比如gpt-4o另一个是把文本转换成向量的Embedding模型比如text-embedding-ada-002。LlamaIndex通过两个独立的客户端类来对接它们。这意味着你不需要自己在本地搭Embedding服务也不需要自己写算法做向量检索LlamaIndex内部已经用向量相似度完成召回。更关键的是Azure OpenAI的部署模型是“以部署名为入口”的。同一个模型可以部署多个实例每个实例有不同的容量、配额、区域。LlamaIndex的集成层恰好把这种部署模型的概念暴露出来了配置起来很直观。初次使用的人只要分清“模型名”和“部署名”基本不会卡住。1.2 这个案例到底要实现什么项目需求非常具体有一批内部运维手册包含服务器重启流程、账号权限申请、常见故障处理等内容。希望员工通过一个简单对话框直接问“服务器密码忘了怎么办”“如何申请数据库权限”系统能给出带文档依据的回答而不是泛泛而谈。所以技术目标有三个能批量读取docs目录下的文档自动做切分和向量化能通过LlamaIndex的查询引擎回答自然语言问题能保留多轮会话上下文用户追答“刚才那个问题里说的临时目录具体在哪”时系统还能理解指代关系。整个项目不追求花哨但要求稳定可复现。Azure OpenAI在这里不是简简单单做一次API调用而是要嵌入到LlamaIndex的索引生命周期里从Embedding到检索再到生成都要打通。2. 环境准备与依赖安装集成工作其实从环境准备就开始有坑了。这里需要准备的东西主要有三块一个能访问Azure OpenAI服务的Azure订阅、一个Python环境、还有若干LlamaIndex相关依赖。本地不需要GPU文档量不大的场景用纯CPU也跑得动。2.1 账号与模型部署前置检查在写任何代码之前先去Azure门户确认以下内容是否就绪已创建Azure OpenAI资源并且状态为已部署已在资源内创建两个模型部署一个给对话模型用一个给Embedding模型用已拿到Endpoint地址、API Key和API版本号。我建议在Azure OpenAI控制台把每个部署的“部署名”记下来。部署名很重要例如你在控制台创建了一个基于gpt-4o的部署部署名可能叫my-gpt4o。后续代码里不能直接用模型名gpt-4o去调而是要指定my-gpt4o。这是Azure OpenAI和标准OpenAI API最明显的差异。模型部署与配置的对应关系可以这样理解用途模型名部署名示例说明对话生成gpt-4omy-gpt4o回答最终问题支持较长上下文文本向量化text-embedding-ada-002my-embedding将文档片段转为向量用于检索新增部署时注意选择区域不同区域支持的模型版本可能不一样。建议选择离业务较近的区域但这不会影响代码只影响网络延迟和配额。2.2 本地Python环境与关键依赖Python版本建议3.10以上。我用的虚拟环境是venv避免依赖冲突。依赖方面LlamaIndex已经按模块拆分了包不能只装一个llama-index就完事最好显式安装Azure OpenAI的集成包python -m venv .venv source .venv/bin/activate pip install -U llama-index-core pip install llama-index-llms-azure-openai pip install llama-index-embeddings-azure-openai pip install python-dotenv如果你嫌麻烦也可以直接pip install llama-index它会带入一堆默认依赖其中通常已经包含Azure相关包。不过显式安装的好处是版本可控出错概率低。LlamaIndex从0.10.x开始把核心功能和云厂商集成分离所以llama-index-core是必须的llama-index-llms-azure-openai负责LLM连接llama-index-embeddings-azure-openai负责Embedding连接。装完后可以先检查版本python -c import llama_index.core; print(llama_index.core.__version__)如果导入报错大概率是某个子包没装全。另外提醒一下openai这个SDK也可能被LlamaIndex依赖拉起来不用单独装。但如果你用了很新的openai要注意它和LlamaIndex的兼容性曾经遇到过SDK升级后参数名变化导致的连锁问题。3. 核心配置与初始化环境准备好后最核心的一步就是把Azure OpenAI的连接参数正确传给LlamaIndex。这一步花不了多长时间但一旦配错后面所有代码都会在运行时爆HTTP错误。我认为这是整个集成案例里最值得细讲的部分。3.1 Azure OpenAI的部署名、模型名与Endpoint三件套Azure OpenAI的连接需要四个参数api_key、azure_endpoint、api_version、deployment_name。前三个是资源级别的最后一个是模型部署级别的。很多人混淆的是model参数和deployment_name参数这两个都要传但职责不同。model指向模型的具体名字例如gpt-4o或text-embedding-ada-002用于LlamaIndex内部判断模型能力deployment_name指向你在Azure控制台里创建的部署名例如my-gpt4o用于实际HTTP请求路由。如果只写model不写deployment_nameLlamaIndex会默认用model的值去请求Azure结果大概率是404因为Azure那边没有同名部署。反过来只写deployment_name不写model有些版本会报被告知模型不存在。因此我习惯把配置统一放到.env文件里代码里不硬编码密钥既安全又方便切换环境AZURE_OPENAI_API_KEYyour-api-key AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ AZURE_OPENAI_API_VERSION2024-06-01 AZURE_OPENAI_DEPLOYMENT_NAMEmy-gpt4o AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAMEmy-embedding注意AZURE_OPENAI_ENDPOINT末尾不要带/否则拼接URL时可能出现双斜杠。api_version建议写当前可用的稳定版本不同模型版本支持的api_version可能不同具体以Azure控制台展示为准。3.2 LlamaIndex全局连接配置在LlamaIndex 0.10.x里推荐使用Settings对象做全局配置。这样后续构建索引和查询引擎时不需要每处都传llm或embed_model。import os from dotenv import load_dotenv from llama_index.core import Settings from llama_index.llms.azure_openai import AzureOpenAI from llama_index.embeddings.azure_openai import AzureOpenAIEmbedding load_dotenv() llm AzureOpenAI( modelgpt-4o, deployment_nameos.getenv(AZURE_OPENAI_DEPLOYMENT_NAME), api_keyos.getenv(AZURE_OPENAI_API_KEY), azure_endpointos.getenv(AZURE_OPENAI_ENDPOINT), api_versionos.getenv(AZURE_OPENAI_API_VERSION), ) embed_model AzureOpenAIEmbedding( modeltext-embedding-ada-002, deployment_nameos.getenv(AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME), api_keyos.getenv(AZURE_OPENAI_API_KEY), azure_endpointos.getenv(AZURE_OPENAI_ENDPOINT), api_versionos.getenv(AZURE_OPENAI_API_VERSION), ) Settings.llm llm Settings.embed_model embed_model这段代码就是整个集成的钥匙。如果你用的是旧版本LlamaIndex可能还需要ServiceContext.from_defaults(llmllm, embed_modelembed_model)但新版本已经统一到Settings了建议直接按新API写。3.3 验证连接是否成功配置写完了不要急着加载文档。先写一个最小的验证脚本确认Azure OpenAI连接没问题resp llm.complete(用一句话解释什么是RAG) print(resp)如果返回结果正常说明LLM链路通了。接着验证Embedding模型embeddings embed_model.get_text_embedding(测试文本) print(len(embeddings))打印出来的向量维度一般是1536对应text-embedding-ada-002的固定维度。如果你发现自己部署的Embedding模型是其他系列输出维度可能不同这没关系只要不报错即可。这个验证环节很多人会跳过但我觉得非常有必要。因为只要把模型配置和密钥问题隔离在“连接阶段”解决后面索引构建报错时你就不需要怀疑是认证问题还是文档解析问题排查范围能缩小一大半。4. 文档索引与检索问答实现连接确认没问题后就可以正式处理文档了。我们的输入是docs目录下的一堆Markdown文件格式比较干净。LlamaIndex的SimpleDirectoryReader可以直接读取目录省去自己写文件遍历逻辑。4.1 加载文档并构建向量索引先读取文档from llama_index.core import SimpleDirectoryReader, VectorStoreIndex reader SimpleDirectoryReader(input_dir./docs) documents reader.load_data() print(f加载了 {len(documents)} 个文档对象)SimpleDirectoryReader支持常见的txt、md、pdf、docx、csv格式。文档解析后LlamaIndex会自动把每个文件拆成一个或多个Document对象。Document是原始信息的容器后面还要经过NodeParser切分成更小的Node。构建索引最直接的方式是index VectorStoreIndex.from_documents(documents)这一步会自动完成文本切分、Embedding调用、向量存储。默认情况下LlamaIndex用句子级切分器把文档切成若干文本块每个块成为一个Node。对于中文文档我建议提前调整切分参数避免把完整语义切断Settings.chunk_size 512 Settings.chunk_overlap 50chunk_size是每个块的最大字符数chunk_overlap是相邻块的重叠长度。512这个值对于一般中文说明文档比较稳太长则检索粒度不够精细太短则容易丢失上下文。重复部分有助于跨块语义衔接但也不是越大越好过大会导致同一内容被重复向量化浪费存储和调用成本。构建索引时每个Node都会调用一次Embedding模型。假如文档数量较多这一步会比较耗时也可能触发Azure配额限制。因此首次构建索引时我会建议先用几篇文档测通流程再全量导入。4.2 自定义查询引擎与提示词索引建好后查询很简单query_engine index.as_query_engine(similarity_top_k5) response query_engine.query(如何申请数据库权限) print(response)similarity_top_k5表示召回5个最相关的文本块。这个值影响效果太小可能漏掉关键信息太大则会让大模型看到太多无关内容既增加token消耗又可能干扰判断。默认查询模板是英文的中文场景下建议自定义提示词让模型严格按照给定文档回答并说明“如果文档中没有明确答案就明确告知不知道”。这一点非常关键能大幅减少幻觉from llama_index.core import PromptTemplate qa_template_str ( 你是内部知识库助手。请根据以下资料用中文回答问题。\n 资料如下\n {context_str}\n 问题{query_str}\n 如果资料里没有相关信息请直接说“资料中没有提到”。\n 回答 ) qa_template PromptTemplate(qa_template_str) query_engine.update_prompts( {response_synthesizer:text_qa_template: qa_template} )修改提示词后回答质量会有明显提升。尤其是内部文档里经常出现缩写和专业术语如果不限定“以资料为依据”模型可能把外部知识混进来。如果还想看到回答引用了哪些文档片段可以遍历response.source_nodesfor node in response.source_nodes: print(来源分数:, node.score) print(内容:, node.text[:200]) print(文件:, node.node.metadata.get(file_name))这对排查“为什么答案这么回答”非常有帮助。尤其是当文档更新后你很快能定位到模型依据的是旧内容还是新内容。4.3 多轮对话场景接入如果只有单轮问答员工问第二句时模型就不知道上一句在说什么了。比如用户先问“服务器崩溃怎么办”再问“那临时文件在哪”这里的“那”指代的是上一句提到的内容。要解决这个问题需要引入对话记忆。LlamaIndex提供了ChatMemoryBuffer和CondenseQuestionChatEngine可以方便地管理多轮上下文from llama_index.core.memory import ChatMemoryBuffer from llama_index.core.chat_engine import CondenseQuestionChatEngine memory ChatMemoryBuffer.from_defaults(token_limit3000) chat_engine CondenseQuestionChatEngine.from_defaults( indexindex, memorymemory, llmllm, ) response chat_engine.chat(数据库账号权限怎么申请) print(response) response chat_engine.chat(需要多久能审批通过) print(response)CondenseQuestionChatEngine的核心逻辑是每次用户提问时先把历史对话和当前问题一起交给LLM提炼成一个独立问题再进行检索。这种方式能保证检索到的内容与当前语境相关同时又不至于把整段历史全部塞给Embedding检索。token_limit3000表示对话记忆最多保留大约3000个token的上下文超出后会按策略丢弃较早的消息。这个值可以根据模型上下文窗口调整但不要设置过大否则既浪费token又引入噪音。5. 常见问题与排查技巧集成过程中我发现真正花时间的不是写代码而是排查各类“连不上”“索引不对”的鬼问题。以下这些问题我几乎都踩过整理成速查表式的内容方便大家直接对照。5.1 Azure连接报401/403如果调用llm.complete()时报AuthenticationError或401 Unauthorized优先检查三件事api_key是否正确且没有空格azure_endpoint是否正确必须包含https://结尾不要有多余的斜杠api_version是否在模型支持范围内。有些时候控制台里显示的“示例代码”会直接包含密钥但复制到本地时可能因为换行符被拆断导致密钥不完整。我建议直接在环境变量里重新粘贴一遍不要手动改动格式。另外注意Azure OpenAI的API Key分为多版本有的资源有多个Key任何一个都可以用但如果你复制错了其他资源的Key就会一直报403。最好在代码里临时打印一次密钥的前四位和后四位人工核验是不是当前资源的密钥。5.2 “Deployment not found”怎么定位如果报错里出现ResourceNotFound或Deployment not found十有八九是deployment_name和model对应关系没对上。这里有一个快速自检方法在Azure控制台打开“模型部署”确认部署名和你填进代码的字符串完全一致包括大小写和连字符。比如你看到部署名是My-GPT4o代码里却写了my-gpt4o也会404。Azure的部署名是区分大小写的不能认为无所谓。还有一个小细节Embedding和LLM的部署名要分开配。很多人只配置了LLM的部署名忘记给AzureOpenAIEmbedding传deployment_name。结果构建索引时全部走默认部署名当然报错。5.3 token超限与请求超时当文档较大或用户问题复杂时可能遇到BadRequestError提示maximum context length exceeded。这种情况说明输入给模型的内容过长。可以采取三个方向调低similarity_top_k减少检索回去的文本块数量调低chunk_size让每次检索到的片段更短在构建查询引擎时使用response_modecompact它会在不超限的前提下尽量保留更多上下文。AzureOpenAI本身也支持超时和重试配置。如果出现TimeoutError或频繁429 RateLimitError可以这样设置llm AzureOpenAI( modelgpt-4o, deployment_nameos.getenv(AZURE_OPENAI_DEPLOYMENT_NAME), api_keyos.getenv(AZURE_OPENAI_API_KEY), azure_endpointos.getenv(AZURE_OPENAI_ENDPOINT), api_versionos.getenv(AZURE_OPENAI_API_VERSION), request_timeout60, max_retries5, )max_retries5表示遇到限流或临时错误时最多自动重试5次能显著提升抖动期的成功率。但也要注意如果持续429说明配额真的不够重试解决不了根本问题需要去控制台申请提高TPM/RPM限制。5.4 中文回答质量差默认工具链对中文不是特别友好常见表现是检索结果不精准、模型回答中夹英文、回答内容与文档无关。我总结下来主要原因是文本切分和提示词。先说切分。LlamaIndex默认的SentenceSplitter是按英文标点断句的对中文标点支持不算太差但遇到中英混排时会把英文句子拆得七零八落。如果你发现召回内容有明显断裂可以换用TokenTextSplitter或自定义分隔符甚至可以把文档先按章节标题预处理成多个小文件再导入。再说提示词。只要在模板中加入“请用中文回答”和“只根据提供的资料回答”基本能解决夹英文和乱发挥的问题。此外similarity_top_k太小时中文同义表述可能召回不全适当提高到5~8一般更好。最后是Embedding模型。这里用的是Azure OpenAI的text-embedding-ada-002它对中文的语义理解能力不算差但如果你对效果要求极高可以考虑支持中文更好的向量模型。不过在此案例中Ada已经能覆盖大部分需求没必要为了炫技更换模型。6. 性能优化与实践经验链路跑通只能算完成一半真正进入实用阶段还要考虑持久化、成本和易用性。这部分是我在完成Basic版本后实际优化过程中总结出来的经验。6.1 索引持久化与增量更新如果每次启动程序都重新读取docs目录并调用Embedding构建索引文档一多就会非常耗时的同时也很烧钱。比较好的做法是首次构建完成后把索引持久化到本地后续启动时直接加载。from llama_index.core import StorageContext, load_index_from_storage # 保存索引 storage_context StorageContext.from_defaults(persist_dir./storage) index VectorStoreIndex.from_documents(documents, storage_contextstorage_context) storage_context.persist() # 加载索引 loaded_index load_index_from_storage( StorageContext.from_defaults(persist_dir./storage) )这里要注意persist_dir必须提前创建或由LlamaIndex自动创建。加载后的loaded_index和原来构建出的对象在使用上完全一致可以直接as_query_engine()。文档更新是另一个常见需求。如果仅仅是往docs目录新增了几个文件没必要全量重建可以用new_doc SimpleDirectoryReader(input_files[docs/new_file.md]).load_data()[0] loaded_index.insert(new_doc)insert会为新文档执行切分和Embedding并追加到已有索引中。这种增量方式既能保留原有索引又能降低时间和成本。不过要注意如果之前修改了chunk_size或切换了Embedding模型那么增量插入的向量和旧索引的向量可能不在同一语义空间建议全量重建一次。6.2 成本与并发调优钱要花在刀刃上。这个案例的成本主要由两部分组成Embedding调用和LLM生成。Embedding价格低但文档多时调用次数非常可观LLM生成价格高但单次调用相对可控。控制成本有几个实操技巧用持久化索引避免重复Embedding这是最明显的一笔节省构建索引时设置embed_batch_size控制在合理范围避免一次性请求过大导致限流查询时用similarity_top_k控制召回量减少无效token设置temperature为较低值比如0.1让回答更稳定减少无谓的“创造性生成长度”。并发方面Azure OpenAI在控制台会显示每分钟请求数限制RPM。如果构建索引时大量并发调用很容易触发429。LlamaIndex内部默认并发数不一定适合你的配额必要时可以降低批大小。我的经验是在脚本开头先做一次小批量测试确认不报429后再跑全量。6.3 封装成服务接口最后一步也是让案例变得有用的关键一步是把查询引擎封装成一个HTTP接口方便内部工具调用。用FastAPI可以快速实现from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI() class QueryRequest(BaseModel): question: str class QueryResponse(BaseModel): answer: str sources: list[str] app.post(/chat, response_modelQueryResponse) def chat(request: QueryRequest): response query_engine.query(request.question) sources [ f{node.node.metadata.get(file_name, unknown)}:{node.text[:100]} for node in response.source_nodes ] return QueryResponse(answerstr(response), sourcessources)封装之后前端或者运维工具只需要发送JSON请求就能获得结果。接口层还可以继续加权限校验、日志记录、访问频控等但起点就是这样一个简洁的端点。在实际项目中我个人的体会是把配置参数独立成.env、索引持久化、再封装成接口这三件事做好整个应用才能真正“用起来”。如果只是在自己的电脑上一个笔记本里跑那始终停留在Demo层面。而一旦走完封装这一步后面无论是接入企业内部聊天工具还是做成Web页面都只是加一层壳的问题。最后再分享一个小技巧Azure OpenAI控制台里修改部署参数后有时需要几分钟才完全生效这时候不要反复改代码先刷新控制台确认状态能少走很多弯路。
