直接用 composer require elasticsearch-php 不行，因为它仅封装 HTTP 请求，不提供向量嵌入、相似度计算等语义搜索必需能力；真正支持语义搜索需选用 sentence-transformers/php-embedder 或结合外部 embedding API，并通过 SQLite 模拟向量库、严格校验模型版本与维度一致性。
为什么直接用 composer require 装 elasticsearch-php 不行？
语义化搜索不是加个客户端就能跑起来的——它需要向量模型、文本嵌入、相似度计算三层能力，而 elasticsearch-php 只负责发 HTTP 请求，不提供 embedding 生成。你装完发现 search() 还是关键词匹配，根本没触发语义逻辑。
真正能开箱支持语义搜索的 Composer 库极少，目前只有两个实用路径：
-
composer require sentence-transformers/php-embedder：轻量，纯 PHP 实现 Sentence-BERT 推理（需 PHP 8.1+、ONNX 支持），适合中小文档集； -
composer require symfony/http-client+ 自建 embedding API：把向量化交给 Python FastAPI/ColBERT 服务，PHP 只做索引路由和混合检索，更稳但多一跳网络。
怎么让 PHP 原生索引支持向量 + 关键词混合查询？
别碰全文索引插件或魔改 MySQL，直接用 SQLite + json1 扩展 + 向量列模拟“轻量向量库”。关键在 schema 设计：
- 主表
docs存id、content、title、metadata（JSON）； - 向量表
doc_embeddings存doc_id和embedding（BLOB，存 float32 数组二进制）； - 查询时用
sqlite3_stmt绑定参数，避免字符串拼接向量数组； - 相似度用余弦距离，PHP 里手写
cosine_similarity()比调扩展快，且可控精度（float32 解包后做点积除模长）。
示例片段：
立即学习“PHP免费学习笔记（深入）”；
function cosine_similarity(string $a_bin, string $b_bin): float {
$a = unpack('f*', $a_bin);
$b = unpack('f*', $b_bin);
$dot = 0; $norm_a = 0; $norm_b = 0;
foreach ($a as $i => $v) {
$dot += $v * $b[$i];
$norm_a += $v ** 2;
$norm_b += $b[$i] ** 2;
}
return $dot / (sqrt($norm_a) * sqrt($norm_b));
}Embedding 更新时为什么文档搜不到新内容？
常见错误是只更新 docs 表却忘了同步 doc_embeddings。更隐蔽的问题是：embedding 模型版本不一致——今天用 sentence-transformers/all-MiniLM-L6-v2 生成的向量，明天换成 paraphrase-multilingual-MiniLM-L12-v2，余弦距离就失效了。
- 每次
composer update后检查vendor/sentence-transformers/php-embedder/version.json是否变更； - 生产环境禁止自动更新 embedding 库，固定
"sentence-transformers/php-embedder": "1.2.0"； - 写入文档前加校验：
if (hash_file('sha256', $model_path) !== $expected_hash) { throw new \RuntimeException('Embedding model mismatch'); }。
PHP 索引层如何对接现有 Elasticsearch 集群？
不是替换，而是分层：PHP 层做 query rewrite 和 rerank。典型流程是——
- 用户输入 “怎么重置管理员密码” → PHP 用 embedding 模型转成向量 → 查本地 SQLite 得 top-20 候选 doc_id；
- 再用这些 doc_id 去 Elasticsearch 执行
terms查询，拿到原始字段（title、updated_at、tags）； - 最后用 BM25 分数 × 0.3 + 余弦分数 × 0.7 加权 rerank，返回结果。
注意：Elasticsearch 的 _source 必须开启，否则拿不到原始 content 做二次 embedding 校验；且 doc_id 字段类型必须设为 keyword，不然 terms 查询会分词失效。
向量维度错一位、SQLite BLOB 解包字节序搞反、模型哈希没校验——这三个点漏掉任意一个，语义搜索就退化成关键词搜索，还查不出原因。
