1. 从一次后端联调卡壳说起：为什么AI Agent项目绕不开这几个组件
去年年底我在做一个AI Agent的检索增强模块，前端对话已经跑通了，但一到"让Agent去查知识库"这一步就各种掉链子。最开始我图省事，把文档切片后直接塞进内存里做关键词匹配，几十条数据还行，一上到几万条，响应时间直接从毫秒级飙到好几秒，而且中文分词基本靠split(" ")，效果惨不忍睹。后来换成ElasticSearch，又踩了中文分词的坑，再后来为了把ES、后端服务、缓存一起管起来，才认真用上了Docker Compose。这一路折腾下来，我发现很多做AI Agent的朋友卡的不是模型本身，而是这些"后端概念"——它们看着像运维的事，实际上直接决定了Agent能不能用、好不好用。
这篇内容就是把这几个概念串起来讲清楚：Docker Compose负责把一堆服务编排起来一键启动，ElasticSearch负责海量文档的检索，IK分词器解决中文切词问题，BM25则是ES默认的相关性打分算法，决定了"哪条结果排前面"。它们不是孤立的，而是一条完整的链路：Compose起服务 → ES存数据 → IK做分词 → BM25算相关性 → Agent拿到高质量上下文。适合正在做AI Agent、RAG（检索增强生成）、知识库问答的后端同学，也适合想补一补检索这块基础的前端或算法同学。下面我按自己实际踩坑的顺序，一个个拆开讲。
2. Docker Compose：把ES、后端、缓存拧成一股绳的编排工具
2.1 Compose到底解决了什么痛点
在没有Compose之前，我要启动一个完整的检索环境，得手动做这些事：先docker run一个ElasticSearch，记住它的端口和网络；再docker run一个Redis；再docker run后端服务，还得手动把它们连到同一个网络里，配环境变量。每次换台机器或者重启，这套命令就得重敲一遍，参数记错一个就连不上。更麻烦的是团队协作，我本地能跑，同事那边因为ES版本不一样，分词结果都对不上。
Docker Compose的核心价值就一句话：用一个YAML文件描述"我要哪些服务、它们怎么配、怎么互相访问"，然后一条命令全部拉起来。它本质上是Docker CLI的上层封装，把一堆docker run的参数固化进docker-compose.yml，让环境变成可版本控制、可复现的东西。对AI Agent项目来说，这意味着你的检索环境可以跟着代码一起提交到Git，谁拉下来都能一键跑起来，这对调试RAG效果特别重要——因为检索结果不稳定，很多时候就是环境不一致导致的。
2.2 一份能直接用的compose文件长什么样
我把自己项目里精简过的一份配置贴出来，包含ES、Redis和后端服务三个部分，你可以直接抄：
version: "3.8" services: elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0 container_name: es-node environment: - discovery.type=single-node - ES_JAVA_OPTS=-Xms1g -Xmx1g - xpack.security.enabled=false ports: - "9200:9200" volumes: - es-data:/usr/share/elasticsearch/data healthcheck: test: ["CMD-SHELL", "curl -s http://localhost:9200 >/dev/null || exit 1"] interval: 10s retries: 5 redis: image: redis:7-alpine container_name: redis-node ports: - "6379:6379" agent-backend: build: . container_name: agent-backend depends_on: elasticsearch: condition: service_healthy environment: - ES_HOST=http://elasticsearch:9200 - REDIS_HOST=redis ports: - "8080:8080" volumes: es-data:这里有几个细节值得说。discovery.type=single-node是单节点模式，开发环境必加，否则ES会尝试组集群然后启动失败。ES_JAVA_OPTS限制堆内存，不设的话ES默认可能吃掉你一半物理内存，笔记本直接卡死。healthcheck配合depends_on的condition: service_healthy，保证后端服务等ES真正就绪了再启动——我早期没加这个，后端启动时ES还没起来，连接直接报错，排查了半天才发现是启动顺序问题。
2.3 网络与依赖：Compose最容易被忽略的两个机制
Compose默认会给整个项目创建一个独立网络，服务之间可以直接用服务名当主机名互相访问。比如上面配置里后端连ES用的是http://elasticsearch:9200，而不是localhost:9200。这一点新手特别容易搞混：在宿主机上你用localhost:9200能访问，但在容器内部，localhost指的是容器自己，必须用服务名。我第一次配的时候后端一直连不上ES，日志里报Connection refused，就是因为写成了localhost。
另一个是depends_on。很多人以为它保证"被依赖的服务完全启动后再启动当前服务"，其实默认的depends_on只保证容器启动顺序，不保证服务内部就绪。ES从容器启动到能响应请求，中间要十几秒。所以必须用healthcheck加condition: service_healthy，这才是真正等就绪。这个坑我在生产环境也见过，有人图省事只写depends_on，结果服务偶尔启动失败，还以为是玄学。
2.4 常见报错与排查思路
docker: unknown command: docker compose这个报错我遇到过，原因是老版本Docker用的是docker-compose（带横杠），新版本才支持docker compose（空格）。如果你敲docker compose报这个错，要么升级Docker到较新版本，要么改用docker-compose命令。Ubuntu上装Compose插件的话，apt install docker-compose-plugin比单独下二进制文件省心。
还有一类问题是端口冲突。ES默认9200，如果本机已经跑了一个ES，Compose启动会报端口被占用。解决办法是把映射端口改掉，比如"9201:9200"，宿主机用9201访问。我习惯在开发环境给每个项目分配不同的端口段，避免这种冲突。
3. ElasticSearch：AI Agent的"记忆检索层"该怎么搭
3.1 为什么Agent需要ES而不是数据库LIKE查询
很多人第一反应是：我数据存MySQL，用LIKE '%关键词%'不也能查吗？能查，但有两个致命问题。第一是性能，LIKE前置通配符会导致全表扫描，几万条数据就开始慢，几十万条直接不可用。第二是相关性排序，LIKE只能告诉你"包含/不包含"，没法告诉你"哪条更相关"。而AI Agent最需要的恰恰是"从海量文档里挑出最相关的几条喂给模型"，这个"最相关"就是ES的强项。
ES底层是Lucene，它把文档内容建成倒排索引——简单说就是"词 → 包含这个词的文档列表"的映射。查"分词"这个词，直接就能定位到所有包含它的文档，不用扫全表。这个结构决定了ES在全文检索上的性能优势。对Agent来说，ES扮演的是"记忆检索层"：用户提问 → 检索相关文档 → 拼进Prompt → 模型生成回答。检索质量直接决定回答质量，这也是为什么RAG项目里ES的配置值得反复调。
3.2 索引、文档、分片：三个必须搞懂的基础概念
索引（Index）相当于关系库里的"表"，是一类文档的集合。比如我会建一个knowledge_base索引存所有知识库文档。文档（Document）是索引里的一条记录，用JSON表示，相当于一行数据。分片（Shard）是索引的物理切分，一个索引可以分成多个分片分布在不同节点上，这是ES能水平扩展的关键。
开发环境我一般设number_of_shards: 1，因为单节点多分片没意义还浪费资源。生产环境根据数据量来，一般单分片控制在30-50GB。还有一个number_of_replicas副本数，开发环境设0省资源，生产至少设1保证高可用。这些在建索引时通过mapping指定：
PUT /knowledge_base { "settings": { "number_of_shards": 1, "number_of_replicas": 0 }, "mappings": { "properties": { "title": { "type": "text", "analyzer": "ik_max_word" }, "content": { "type": "text", "analyzer": "ik_max_word" }, "created_at": { "type": "date" } } } }注意analyzer字段，这就是下一节要讲的IK分词器的接入点。text类型会被分词，适合全文检索；如果某个字段要精确匹配（比如ID），用keyword类型，它不分词。
3.3 写入慢还是磁盘有问题：一套可落地的判断指标
热词里有个很实际的问题："ES怎么判断写入慢，是磁盘问题还是别的？"这个问题我在生产环境真排查过，分享一套判断思路。ES写入慢，原因通常分三类：磁盘IO瓶颈、段合并（merge）压力、JVM GC。判断方法如下。
先看iostat -x 1，重点看%util和await。如果%util长期接近100%，await很高，那基本是磁盘IO到瓶颈了，尤其是机械盘或者云上低配SSD。ES写入是"先写内存buffer，再刷到translog，最后落segment"，对磁盘随机写要求高。
再看ES自己的指标，通过_nodes/stats接口：
curl -s "localhost:9200/_nodes/stats/indices,os,jvm" | python -m json.tool关注indices.merges.total_time_in_millis，如果merge时间占比很高，说明段合并吃掉了大量IO。可以适当调大refresh_interval（默认1秒），减少refresh频率，降低merge压力。JVM方面看jvm.gc.collectors.old.collection_time_in_millis，如果老年代GC频繁且耗时长，说明堆内存不够，需要调大ES_JAVA_OPTS的-Xmx，但不要超过物理内存的50%，且不超过32GB（超过会失去指针压缩优化）。
我当时的结论是：磁盘%util高 + merge时间长 + GC正常，那就是磁盘IO问题，换了SSD后写入速度提升明显。这个排查链路比"感觉慢就加内存"靠谱得多。
3.4 SpringBoot接入ES的版本兼容坑
热词里出现了this version of the jdbc driver is only compatible with elasticsearch version，这是典型的版本不匹配报错。SpringBoot接入ES有两条路：一是用spring-boot-starter-data-elasticsearch，二是用官方的elasticsearch-java客户端。前者版本和SpringBoot强绑定，比如SpringBoot 2.x默认带的ES客户端版本可能和你服务端的ES版本对不上，就会报兼容性错误。
我的建议是：服务端ES版本和客户端版本尽量保持一致。用SpringBoot 2.x的话，可以在pom.xml里显式覆盖ES客户端版本：
<properties> <elasticsearch.version>8.11.0</elasticsearch.version> </properties>这样Maven会拉取指定版本的客户端。如果还是报兼容错误，检查是不是引入了elasticsearch-rest-high-level-client这种老客户端，8.x之后官方主推新的elasticsearch-java客户端，老客户端在新版本上支持有限。这个坑我踩过一次，排查了半天才发现是依赖传递带进来的旧版本。
4. IK分词器：中文检索效果的分水岭
4.1 为什么ES默认分词器对中文"无能为力"
ES默认的标准分词器（standard analyzer）是按字符切分的，对英文没问题，但中文会被切成一个个单字。比如"人工智能技术"会被切成"人""工""智""能""技""术"，然后建索引。这样查"人工智能"时，匹配的是这几个单字，相关性计算会非常粗糙，而且容易召回一堆不相关的文档。这就是为什么中文场景必须装IK分词器。
IK分词器的核心是基于词典的分词，它内置了一个中文词典，能把"人工智能"识别成一个词而不是六个字。它有两种模式：ik_max_word（最细粒度，会把"中华人民共和国"切成"中华人民共和国""中华人民""中华""华人""人民共和国"等）和ik_smart（最粗粒度，只切"中华人民共和国"）。建索引时用ik_max_word提高召回，查询时用ik_smart提高精度，这是常见搭配。
4.2 安装IK的两种方式与版本对齐
IK分词器是ES的插件，版本必须和ES严格一致，8.11.0的ES就得装8.11.0的IK，差一个小版本都可能启动失败。安装方式有两种。
第一种是进容器手动装：
docker exec -it es-node bash bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.11.0/elasticsearch-analysis-ik-8.11.0.zip装完必须重启ES容器。第二种是在Dockerfile里预装，适合生产环境：
FROM docker.elastic.co/elasticsearch/elasticsearch:8.11.0 RUN bin/elasticsearch-plugin install --batch https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.11.0/elasticsearch-analysis-ik-8.11.0.zip我推荐第二种，因为环境可复现，不用每次手动进容器装。装完用这个命令验证：
curl -X POST "localhost:9200/_analyze" -H 'Content-Type: application/json' -d' { "analyzer": "ik_max_word", "text": "人工智能技术" }'如果返回的是"人工智能""技术"这样的词，说明装好了。如果报analyzer [ik_max_word] not found，那就是没装成功或者没重启。
4.3 自定义词典：让分词贴合你的业务
IK内置词典覆盖通用词汇，但你的业务可能有专有名词。比如做医疗Agent，"心肌梗死"必须是一个词，不能被切成"心肌""梗死"。这时候就要用自定义词典。在IK的config目录下有个IKAnalyzer.cfg.xml，配置扩展词典路径：
<properties> <comment>IK Analyzer 扩展配置</comment> <entry key="ext_dict">custom/mydict.dic</entry> </properties>然后在config/custom/mydict.dic里一行一个词。改完重启ES生效。这个功能在垂直领域Agent里特别有用，我做过一个法律知识库，把"不当得利""无因管理"这些法律术语加进词典后，检索准确率提升很明显。注意词典文件要用UTF-8无BOM编码，否则中文会乱码，这个坑我踩过。
5. BM25：决定"哪条结果排前面"的打分算法
5.1 BM25到底在算什么
检索出来一堆文档，谁排第一？这就是相关性打分要解决的问题。ES 5.0之后默认用BM25算法。BM25的核心思想可以拆成三个因子：词频（TF）、逆文档频率（IDF）、文档长度归一化。
词频好理解，一个词在文档里出现越多，越可能相关。但BM25对词频做了饱和处理——出现10次和出现100次，得分差距不会线性拉大，因为一个词出现太多次可能是堆砌。IDF是说，一个词如果在所有文档里都出现（比如"的""是"），那它区分度低，权重就小；反之"心肌梗死"这种只在少数文档出现的词，权重就大。文档长度归一化是说，长文档天然更容易命中关键词，所以要惩罚长文档，避免长文档靠"字多"霸榜。
用生活化的类比：BM25像一个阅卷老师，不只看你答对几个关键词（词频），还看这个关键词是不是"稀有考点"（IDF），同时考虑你答卷的长度（长度归一化），综合给分。这个设计比早期的TF-IDF更合理，也是它成为默认算法的原因。
5.2 调参：k1和b这两个旋钮怎么拧
BM25有两个可调参数：k1控制词频饱和速度，默认1.2；b控制文档长度归一化程度，默认0.75。k1越大，词频的影响越持续；b越大，长文档惩罚越重，b=0则完全不考虑长度。
大部分场景用默认值就行，但有些情况值得调。比如你的文档长度差异极大（有的几十字，有的几万字），可以适当调大b，加强对长文档的惩罚。如果你的查询词在文档里出现次数普遍很少，可以调小k1，让词频影响更平缓。调参方式是在查询时指定：
{ "query": { "match": { "content": { "query": "心肌梗死 治疗", "boost": 1.0 } } } }或者在索引mapping里用similarity自定义。我的经验是：先别急着调BM25，先把分词和字段权重调好。很多时候检索效果差不是BM25的问题，而是分词没分对，或者该给标题加权重没加。标题命中的权重通常应该高于正文，可以用multi_match的fields加^符号：
{ "query": { "multi_match": { "query": "心肌梗死", "fields": ["title^3", "content^1"] } } }这样标题命中算3倍权重，效果立竿见影。
5.3 BM25和向量检索的关系：不是替代而是互补
现在做AI Agent，很多人一上来就上向量检索（embedding），觉得BM25过时了。我的实际经验是：两者互补，混合检索效果最好。BM25擅长精确关键词匹配，比如用户搜"ES 8.11.0"，向量检索可能把语义相近但版本不对的文档排前面，而BM25能精确命中版本号。向量检索擅长语义理解，比如用户问"怎么让搜索更准"，BM25可能匹配不到"相关性调优"的文档，但向量能。
所以成熟的做法是混合检索：BM25召回一批，向量召回一批，然后用RRF（倒数排名融合）或加权融合合并结果。ES 8.x已经原生支持向量字段和kNN检索，可以在同一个查询里同时做BM25和向量检索。这个组合我在项目里实测，比单用任何一种召回率都高。对AI Agent来说，检索质量就是回答质量的上限，值得在这上面多花功夫。
6. 把四个组件串成一条可复现的链路
6.1 从零到跑通的完整顺序
把前面讲的串起来，一个可复现的搭建顺序是这样的。第一步，写好docker-compose.yml，包含ES和你的后端服务，ES挂载数据卷。第二步，用Dockerfile给ES预装IK分词器，保证版本一致。第三步，docker compose up -d启动，用docker compose ps确认ES健康。第四步，建索引时指定IK分词器和mapping。第五步，后端用ES客户端写入文档、执行检索，检索时用multi_match加字段权重。第六步，观察检索结果，根据效果调分词词典和BM25参数。
这个顺序的关键是每一步都可验证：ES起来了用curl测，IK装了用_analyze测，索引建了用_mapping测，检索效果用真实query测。不要一口气全配完再调，那样出问题根本不知道是哪一环。
6.2 几个我反复踩过的坑
第一个坑是数据卷权限。ES容器里的进程UID和宿主机挂载目录的权限不匹配，会导致ES启动时报AccessDeniedException。解决办法是给挂载目录设权限，或者用命名卷（named volume）让Docker自己管。我上面配置里用的es-data就是命名卷，省心。
第二个坑是refresh_interval。默认1秒refresh一次，写入量大时会产生大量小segment，merge压力大。批量导入数据时可以临时设成-1（关闭自动refresh），导完再设回来，导入速度能快好几倍。
第三个坑是查询时的分词器。建索引用ik_max_word，查询时如果也用ik_max_word，可能召回过多；用ik_smart更精准。这个搭配不是绝对的，要看你的数据特点，建议两种都测一下对比效果。
6.3 这套东西对AI Agent到底意味着什么
回到最开始的问题：为什么AI Agent项目要懂这些后端概念？因为Agent的"智能"不只来自模型，还来自它拿到的上下文。检索层搭得好，模型拿到的是精准、相关的文档，回答自然靠谱；检索层搭得烂，模型再强也是"垃圾进垃圾出"。Docker Compose保证环境可复现，ES提供高性能检索，IK解决中文分词，BM25保证相关性排序——这四个组件构成了Agent的"记忆检索底座"。
我自己最大的体会是：别把检索当成黑盒。很多人调RAG效果不好，就一味换模型、调Prompt，其实问题往往出在检索。花时间把分词、字段权重、BM25参数调明白，比换个大模型带来的提升更直接、更省钱。这套东西不难，但需要动手跑一遍、踩几个坑才能真正理解。建议你照着上面的配置自己搭一遍，用真实数据测检索效果，比看十篇文章都管用。
