经常有同学拿着业务文档过来问能不能把 LLM 直接接到我们的数据库或者文件目录上让它变成内部问答助手我的回答通常是能但如果你以为把数据连上去就算完成了 80%实际完成的大概只有 21%。Connecting an LLM to Your Data Is the 21% Solution这句话要表达的就是这件事连接只是开始剩下 79% 的工作在数据治理、检索质量、评测迭代和权限控制里。这篇文章就用工程视角拆开这 79%并给出一套可以照着跑的通用方案。先说清楚这篇文章能给你什么一套 LLM 数据接入的完整链路分析四种主流接入路径的对比一个最小可运行的“数据问答”服务代码骨架接口调用和批量任务的示例以及常见问题排查清单。适合正在做 RAG、知识库、AI Agent 或企业内部问答系统的开发者。全文不会写死某一款商业产品的内部参数凡是涉及启动脚本、接口路径和资源占用的地方都会标注清楚哪些是通用模板、哪些需要按实际环境替换。1. 核心能力速览这次我们看的不是一个开箱即用的仓库而是一条技术路线。很多 LLM 数据接入项目之所以失败不是模型不够强而是连接完成之后没人继续投入。维度说明主题LLM 与业务数据集成典型形态是 RAG 知识库、企业问答、AI Agent 数据接入核心问题为什么“把 LLM 接到数据”只算完成了 21% 的工作关键技术数据清洗、文本切分、向量化、检索排序、重排 Rerank、Prompt 编排、评测迭代部署形态本地模型 向量库 API 服务或云端 API 模型 向量库硬件门槛取决于模型规模只跑检索服务门槛低本地跑 7B/8B 模型需要再评估批量能力支持文档批量索引、任务队列、失败重试接口能力REST API、OpenAI 兼容接口、MCP 扩展数据安全必须做权限隔离、脱敏、合规授权适合读者RAG 开发者、知识库搭建者、AI 应用工程师从材料看这类项目在网上的讨论热点主要集中在这几个方向LLM 框架、LLM Agent、MCP Client 与 LLM 连接、LLM API、本地数据访问。它们本质都在解决同一件事模型本身没有业务数据它需要一条可控、可更新、可评估的数据通道。2. 为什么“接到数据”只是 21%LLM 数据接入完整链路“21%”不是一个精确测量值而是一种提醒。很多团队以为把数据库连接串写好、把文档塞进向量库系统就能正常问答了但实际落地时会发现后面还有一堆问题文档格式五花八门、切分后语义断裂、检索命中不相关、回答引用错乱、敏感数据越权访问。为了看清楚剩余工作量可以把 LLM 数据接入拆成一个经验性的 100% 链路环节经验占比主要内容数据接入20%数据源连接、文件导入、增量更新、格式转换数据清洗与切分20%去重、格式归一化、章节识别、Chunk 切分、元数据管理索引与检索优化20%Embedding 模型选择、向量库选型、混合检索、Rerank生成与编排15%Prompt 模板、上下文管理、Agent 工具调用、MCP 接入评测与迭代15%构建评测集、检索命中率、回答忠实度、回归测试安全合规与运维10%权限隔离、脱敏、日志审计、模型版本与向量版本管理数据接入本身只占约 20%也就是标题里说的“21%”。它会很快见效因为界面能看到了、数据库能连上了、文件能上传了造成一种“马上要完成”的错觉。但后面每一个环节都可能让项目返工切分粒度不对检索质量差Embedding 模型不适合领域文本召回率低没有评测集改了一版 Prompt 也没人知道是变好还是变差。所以做这件事的正确顺序应该是先明确业务问题和评测方式再选择接入路径最后才动手连数据。如果反过来先花两周把数据全部灌进去很可能第三周就发现检索效果不可用需要重新设计数据组织方式。3. 适用场景与使用边界LLM 数据接入最典型的适用场景有这些企业内部知识库问答把操作手册、制度文档、FAQ 变成可检索的问答服务。研发文档辅助把接口文档、技术方案、历史故障记录接入模型提升排障效率。领域情报分析把行业报告、政策文件、新闻资料切分后做定向问答。客服机器人把商品信息、售后规则、订单查接口包装成工具让 Agent 自主调用。数据查询入口通过自然语言生成 SQL 或调用内部 API让非技术人员访问数据。不适合的场景也要说清楚。如果数据本身质量很差比如大量空值、重复、过期那接入 LLM 之前必须先把数据治理做掉否则模型只会把错误信息包装得更自信。对时效性要求极高的场景比如实时股价、实时库存单纯的 RAG 离线索引不够还需要配合 API 实时拉取。对数据安全要求极高、完全不能出内网的场景不要直接调用外部 API除非完成合规评估并做好传输加密。使用边界方面这里必须强调几点。涉及个人隐私、用户信息、版权材料、人脸照片、声音样本的业务数据接入前需要取得合法授权并做脱敏处理。爬虫或网页采集只能访问和保存你有权使用的数据。企业知识库要做好权限隔离不能出现低权限用户通过问答旁路读到高权限文档的情况。商用之前要对模型输出做人工复核避免模型幻觉导致错误结论对外传播。4. 环境准备与前置条件LLM 数据接入的环境准备没有绝对统一的标准因为模型路线不同硬件差异很大。但可以分两条路线对照看。4.1 选型思路第一条路线是“纯 API 模式”模型走云端 OpenAI 兼容接口或国内大模型 API本机只负责数据处理、向量化、检索和 API 服务。这种模式硬件要求最低普通开发机能跑起来。但要注意业务数据会经过第三方接口需要先做合规评估。第二条路线是“本地模型模式”LLM 和 Embedding 模型都部署在本机或内网。数据不出内网安全更好但硬件压力更大。如果只跑检索服务和 Embedding 模型资源占用很低如果还要本地跑 7B/8B 开源模型建议准备 16GB 以上内存有 8GB 以上显存的 NVIDIA 显卡会更流畅具体占用要以本机实际模型精度和上下文长度为准。4.2 通用检查清单拿到一个新项目时先按下面这个清单过一遍操作系统Linux、macOS、Windows 均可但生产环境更建议 Linux。Python建议 3.10 以上具体以框架要求为准。GPU 驱动与 CUDA如果本地推理先确认驱动版本和nvidia-smi能正常输出。磁盘空间模型文件、向量库、原始文档需要单独规划别跟系统盘混在一起。端口规划Web 服务默认 8000向量库 6333 或 19530模型服务 8001 或 11434避免冲突。网络策略本地服务只监听127.0.0.1还是0.0.0.0要按访问范围决定。数据目录原始数据、切分缓存、向量库持久化目录、日志目录分开管理。目录结构参考rag-demo/ ├── app.py ├── requirements.txt ├── .env.example ├── data/ │ ├── docs/ # 原始文档 │ ├── chunks/ # 切分后的文本缓存 │ └── db/ # 向量库持久化目录 └── logs/ # 服务日志这套目录结构不复杂但能避免后面踩到“不知道文件被写到哪里”的坑。早期项目不需要一次性把组件都拉满先跑通最小闭环再逐步加 Rerank、Agent、MCP。5. 把数据送进 LLM 的四种路径LLM 不会自动知道你的数据。所谓“接入数据”本质是选择一条路径把数据从业务系统搬运到模型可用的范围里。常见的有四种。5.1 直接塞进上下文把文档内容直接拼到 Prompt 里。实现最直接适合数据量小、单次任务长度可控的场景。缺点也很明显Token 容量有限长文档会被截断每次问答都要重新传全文成本高、速度慢多个文档之间无法做横向检索。5.2 RAG 检索增强生成先把文档切分成 Chunk用 Embedding 模型转成向量存入向量库。问答时先用问题检索出最相关的几个 Chunk再拼进 Prompt 交给模型回答。这是目前大多数知识库项目的首选适合数据量大、实时更新的场景。后续所有检索优化、切分调优、Rerank 都是围绕这条路径展开。5.3 微调模型把领域数据用于模型训练让知识固化进权重。适合模型行为需要高度稳定、Prompt 每次都带大数据不现实的场景。但成本高、训练周期长、知识更新慢不是普通团队应该一开始就走的路。现实情况是大部分业务根本不需要微调RAG 已经能解决 80% 的问题。5.4 Agent 工具调用与 MCP把数据源封装成工具函数或 MCP Server让模型按需调用。比如查询订单接口、查天气、读写数据库都可以作为工具注册给 Agent。这种方式适合实时数据和动态操作是 RAG 的重要补充。近期很多人讨论MCP Client 与 LLM 连接就是在同一个体系里把外部能力标准化地暴露给模型。四种路径对比路径实现复杂度数据量实时性成本适合场景直接塞上下文低小高高 Token 成本小工具、单文档问答RAG中大中中知识库、文档问答微调高中低高高稳定行为、领域风格Agent/MCP中高大高中实时查询、操作型任务从实践看RAG 是大多数项目的起步点Agent/MCP 是第二步扩展微调留给少数有明确 ROI 的场景。6. 搭建最小可运行的“数据问答”服务下面给出一段最小可运行的 FastAPI 代码。重点不是做到生产级而是让你看清完整数据流文件 - 切分 - 向量化 - 存储问题 - 向量化 - 检索 - 拼 Prompt - 调 LLM。你只需要替换模型地址和向量库配置就能跑通一个基础版本。6.1 准备依赖requirements.txt内容如下fastapi uvicorn chromadb openai python-multipart注意openai库在这里只作为 Client 使用可以通过base_url指向任何 OpenAI 兼容接口包括本地部署的模型服务或 Ollama 服务不一定必须连接 OpenAI 官方。6.2 服务端代码app.py的参考实现import os from fastapi import FastAPI, UploadFile, File from pydantic import BaseModel import chromadb from openai import OpenAI app FastAPI() # 向量库持久化 vector_client chromadb.PersistentClient(path./data/db) collection vector_client.get_or_create_collection(namedocs) # 模型服务地址按实际环境替换 LLM_BASE_URL os.getenv(LLM_BASE_URL, http://127.0.0.1:8001/v1) LLM_MODEL os.getenv(LLM_MODEL, qwen2.5:7b) EMBEDDING_MODEL os.getenv(EMBEDDING_MODEL, bge-m3) client OpenAI(base_urlLLM_BASE_URL, api_keyEMPTY) def split_text(text: str, chunk_size: int 500): # 简化切分逻辑真实项目建议结合段落标题做语义切分 return [text[i:i chunk_size] for i in range(0, len(text), chunk_size)] def embed(text: str): resp client.embeddings.create(inputtext, modelEMBEDDING_MODEL) return resp.data[0].embedding class QueryRequest(BaseModel): question: str top_k: int 3 app.post(/ingest) async def ingest(file: UploadFile File(...)): raw (await file.read()).decode(utf-8, errorsignore) chunks split_text(raw) ids [f{file.filename}-{i} for i in range(len(chunks))] vectors [embed(c) for c in chunks] collection.add( idsids, embeddingsvectors, documentschunks, metadatas[{source: file.filename}] * len(chunks) ) return {status: ok, chunks: len(chunks)} app.post(/query) async def query(req: QueryRequest): q_vec embed(req.question) hits collection.query( query_embeddings[q_vec], n_resultsreq.top_k ) docs hits[documents][0] sources hits[metadatas][0] context \n.join(docs) prompt ( f请基于以下材料回答问题。如果材料里没有答案请直接说明未知。\n\n f材料\n{context}\n\n问题{req.question} ) resp client.chat.completions.create( modelLLM_MODEL, messages[{role: user, content: prompt}], temperature0.3 ) return { answer: resp.choices[0].message.content, sources: sources }这段代码是简化骨架并不等于生产级实现。几个地方要注意split_text只按固定字符数切分真实项目要考虑标题、段落和语义边界embed调用的是 OpenAI 兼容接口不同部署服务的模型名需要替换上传 PDF、Word 需要额外解析库上面示例只处理纯文本。6.3 启动服务pip install -r requirements.txt uvicorn app:app --host 0.0.0.0 --port 8000如果端口 8000 被占用换成 8010 或者 9000uvicorn app:app --host 0.0.0.0 --port 80106.4 用 curl 测试# 上传文档 curl -X POST http://127.0.0.1:8000/ingest \ -F file./data/docs/readme.md # 发起问答 curl -X POST http://127.0.0.1:8000/query \ -H Content-Type: application/json \ -d {question: 这个服务怎么部署, top_k: 3}启动后主要观察三件事/ingest返回的chunks数量是否合理/query返回的sources是否和问题相关LLM 端在请求时是否有稳定输出。如果sources不相关问题大概率出在切分或 Embedding而不是模型本身。7. 功能测试与效果验证一个 LLM 数据接入服务能不能用不能只看“能回话”。建议按下面的维度逐项测试。7.1 基础问答测试上传一份操作手册问一个答案明确的问题。预期是最佳答案在返回的sources里能找到出处。判断标准回答内容与原文一致没有把材料没写的东西编出来。7.2 跨文档问答测试上传两份互补的文档问一个需要综合两处信息的问题。这时如果只检索到一份文档说明检索召回不足需要调整 Chunk 大小、top_k或加入 Rerank。7.3 中文与编码测试上传带中文的 TXT、Markdown、PDF。PDF 和 Word 需要额外解析纯文本示例通常直接可用。中文乱码多半是文件编码不是 UTF-8先用编辑器转码再上传。7.4 批量索引测试准备 20 个文档全部走/ingest写入结束后查询向量库总量确认没有漏写。批量操作时注意控制并发后面会单独讲。7.5 长文本与多轮测试把长文档整段丢进去看是否截断或超时连续问多个有关联但不同的问题看上下文是否被正确拼接。很多 RAG 失败的根源是上下文窗口管理没做好导致模型看到的是截断后的残缺信息。测试用例参考表测试项输入预期结果判断方式单文档问答上传操作手册问明确问题回答引用了手册内容核对原文与回答跨文档问答两份互补文档问综合问题回答覆盖两个文档信息检查来源列表与回答中文 CSV/TXT中文编码的文件检索内容无乱码查看返回 Chunk超长文档超过上下文长度的文档片段服务不崩溃回答可接受观察日志与耗时批量索引20 个文件同时写入全部成功状态码 200查看向量库数量对抗问题故意问材料外内容回答“未知”或引用不相关材料人工判断如果基础问答已经稳定下一步建议立刻做评测集把所有常见问题收集到一份 JSON 文件里每次改完检索策略就重跑一遍看“正确回答率”是涨还是跌。没有评测集所有调优都是碰运气。8. 接口 API 与批量任务服务一旦提供 REST API就可以接到前端、企业微信机器人、内部工具里。上面示例暴露了/ingest和/query两个接口。实际使用中还会需要/delete、/collections、/health等扩展。批量索引不能靠手动一个文件一个文件上传写一个批量脚本遍历目录import glob import requests base_url http://127.0.0.1:8000 for path in glob.glob(./data/docs/**/*.md, recursiveTrue): with open(path, rb) as f: resp requests.post( f{base_url}/ingest, files{file: f}, timeout60 ) print(path, resp.status_code, resp.json())当文件数量变大后要注意三个问题失败重试上传超时或网络抖动时需要重试。建议指数退避第一次失败等 1 秒第二次等 2 秒最多重试 3 到 5 次。同时把失败文件记录到日志跑完统一处理。幂等性同一个文件重复上传会导致向量库重复数据。建议用文件 Hash 作为 ID 的一部分重复上传时先删旧数据再写入。队列化如果单次任务超过几百个文件不要直接用脚本同步循环可以引入 Celery、RQ、Arq 或消息队列把索引任务异步化。接口调用超时设置在批量场景下特别重要。推理模型响应慢尤其本地模型建议把超时时间设置到 120 秒以上。如果你的业务侧对延迟敏感可以先把检索结果和答案异步返回或者用 SSE 流式输出。MCP 是这个链路里的另一个发展方向。如果你把数据源封装成 MCP Server模型就能通过工具协议直接访问数据库、文件系统或内部服务而不需要每次手工同步到向量库。适合实时性要求高的数据查询场景。9. 资源占用与性能观察部署完成后资源占用是判断系统是否健康的第一步。最直接的观察方式# 实时看显存占用 nvidia-smi -l 1 # 看 CPU 和内存 htop # 如果服务跑在 Docker 里 docker stats影响资源占用的因素主要有这几项Embedding 批量大小批量越大内存占用越高速度越快但容易把内存打满。Chunk 长度与数量越长越容易导致向量维度计算和存储膨胀检索时内存占用也随之增大。向量库持久化模式Chroma 等库默认会把数据映射到磁盘但查询时仍会占用内存。LLM 上下文长度上下文越长显存和内存占用越高响应越慢。并发数并发把多个请求同时送进模型推理显存占用会直接翻倍。具体数字不做猜测因为这完全取决于模型版本、量化精度、上下文长度和并发数。稳妥的做法是先小批量测试记录峰值再按目标并发预留 20% 到 30% 余量。降低资源占用的通用手段包括Embedding 请求做批量合并限制同一时刻的 LLM 并发数控制上下文窗口长度使用量化版本模型把向量库放到独立实例对不常用的数据做冷备。10. 常见问题与排查方法问题现象可能原因排查方式解决方案文档上传后检索不到切分失败、Embedding 异常、未保存成功看/ingest返回的 chunk 数量查向量库 count检查代码日志重新索引该文件回答和材料无关检索命中不相关、上下文截断、Prompt 不清晰打印检索到的 chunks 查看相关性调整 Chunk 大小、top_k加 Rerank中文乱码文件编码不是 UTF-8、PDF 需要 OCR用文本编辑器打开源文件确认编码转码后重新上传换解析库显存或内存不足模型太大、并发过高、Embedding 批量过大运行nvidia-smi或htop观察峰值换小模型、降低并发、加量化端口被占用默认端口被其他服务占用netstat -tlnp或lsof -i:8000换端口或停掉占用进程API 超时LLM 推理慢、网络问题、请求体过大查看请求耗时和日志加大 timeout、异步化、限制单次内容长度向量库文件损坏异常退出、Chroma 版本不兼容看启动日志和数据库目录状态删除data/db重新索引权限或认证失败API Key、模型名、Base URL 配置错误用 curl 直接请求模型服务验证更新环境变量和配置其中最难排查的是“回答和材料无关”这一类。它通常不是单一原因而是切分、Embedding、检索、Prompt 一起叠加的结果。遇到这种情况建议把检索出的 chunks 打印出来人工看一遍。如果 chunks 本身就不相关说明问题在检索侧如果 chunks 相关但回答错误问题在生成侧如果 chunks 和回答都还行但用户觉得不满意问题可能在看不懂的 Prompt 需求或评测标准不一致上。11. 最佳实践与使用建议项目能不能长期用靠的是工程习惯不是换更大的模型。第一先小参数跑通再逐步放大。第一次测试用一份文档、一个最小的top_k确认链路完整再扩大数据范围。很多失败项目都是“全量灌入后再调优”到那个时候连问题出在哪一步都分不清。第二建立评测集。从真实用户问题里收集至少几十条覆盖单文档、跨文档、未知问题、边界问题。每次改动之后统一跑一遍记录正确率。不要靠“感觉回答变好了”来做判断。第三数据目录和版本管理要规范。原始数据、切分后的文本、向量库、日志分目录存放。对向量库做版本管理至少要做到“出问题能回滚到昨天”。第四接口服务要限制访问范围。开发环境监听127.0.0.1如果必须给局域网使用把端口收敛到内网并加认证暴露到公网时必须使用网关、鉴权和 HTTPS。第五数据合规不能省。涉及个人隐私、版权、人脸、声音、内部资料的数据必须确认有合法授权做必要脱敏并对模型输出做安全限制防止通过问答旁路访问越权信息。第六注意测试环境与生产环境分离。在测试环境验证模型效果在生产环境做权限与稳定性控制两者不要混用。12. 总结与下一步回到开头那个命题把 LLM 接到数据只是 21%。但这 21% 值得先做因为它是整个系统的地基没有它后面的清洗、检索、评测都无从谈起。真正决定项目成败的是你愿不愿意把剩下 79% 的时间花在数据切分、检索质量、评测集和数据安全上。如果你正在做知识库问答下一步不是继续堆模型而是把你手头的几十条真实问题整理成评测集每改一次检索策略就重跑一遍。这个习惯的价值远大于换一个更大的模型。先跑通最小 Demo再逐步引入 Rerank、MCP、Agent 和知识图谱这条路会越走越顺。