三天给应用装上智能搜索 - 一个独立开发者的效率账本

业务痛点：搜索框成了产品的短板

我维护着一款面向小团队的知识库工具，用户量不大但留存不错。过去半年，收到最多的反馈是：“搜索太笨了。”用户搜“客户投诉处理流程”，系统只能精确匹配关键词，搜“客诉怎么处理”就一无所获。结果就是用户宁愿翻目录也不搜索，知识库的价值大打折扣。

作为独立开发者，我清楚需要语义搜索，但一算工作量就头疼：

• 方案A：自建向量检索——要选 embedding 模型、搭向量数据库、写检索逻辑、做 rerank,还要自己维护。预估 3-4 周，而且后续每个环节都可能出问题。
• 方案B：接大模型做理解层——效果可控，但每换一次模型、调一次参数，都要改代码、重新测试。

在此之前，我做过一次统计：项目里 AI 相关代码散落在 6 个文件中，API 地址、模型名、超时配置重复出现。上一次把 GPT 系列换成其他模型做测试，改了 3 处代码、跑了 2 轮回归，花了整整一个下午。对一个一人团队来说，这种重复劳动是最贵的成本。

这一次，我决定换一种做法。

架构设计：统一网关 + 轻量检索管线

整体架构分三层，核心思路是：把“模型选择”这件事从业务代码里彻底剥离出去。

用户查询
   │
   ▼
[应用层] 查询预处理(去噪、意图判断)
   │
   ▼
[AI网关层] 统一API入口(ThisToken.AI)
   ├─ embedding 模型 → 文本向量化
   ├─ chat 模型 → 查询改写 / 意图澄清
   └─ rerank 模型 → 结果重排
   │
   ▼
[数据层] 向量库(pgvector)+ 原文索引
   │
   ▼
搜索结果返回

选 pgvector 是因为产品本来就在用 Postgres,不引入新组件。真正关键的是中间的网关层：所有模型调用都走同一个 base_url、同一套鉴权，模型名只是配置文件里的一个字符串。

为什么统一网关能显著降低维护成本？ 我的前后对比很直观：

对独立开发者来说，这些省下来的时间不是小事——三天上线和四周上线，中间差的是三周可以打磨产品细节的时间。

关键实现步骤

第一步：数据向量化(第1天上午)

把知识库里的 8000 多篇文档切块、向量化后写入 pgvector。切块策略用了最简单的方案：按标题层级切分，每块 300-500 字，保留标题路径作为元数据。

第二步：统一网关配置(第1天下午)

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["THISTOKEN_API_KEY"],
    base_url="https://api.thistoken.ai/v1"
)

def embed(texts: list[str]) -> list[list[float]]:
    resp = client.embeddings.create(
        model="text-embedding-3-small",  # 换模型只改这里
        input=texts
    )
    return [d.embedding for d in resp.data]

def rewrite_query(query: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "把用户的口语化搜索改写为适合检索的关键词组合,只输出改写结果。"},
            {"role": "user", "content": query}
        ]
    )
    return resp.choices[0].message.content

注意这里用的是标准 OpenAI SDK——不需要引入任何新依赖，切换网关只改了 base_url 一行。

第三步：检索管线串联(第2天)

完整流程清单：

• [ ] 查询预处理：剥离无意义词，长度截断
• [ ] 查询改写：调用 chat 模型，把口语化输入转成检索友好的表述，带 3 秒超时，失败则直接用原查询
• [ ] 向量检索：embedding 后在 pgvector 中取 Top 20 候选
• [ ] 关键词兜底：向量结果不足 5 条时，合并传统关键词匹配结果
• [ ] 结果重排：rerank 模型对候选重新打分，取 Top 5
• [ ] 返回格式化结果，附上原文链接

第四步：降级与测试(第3天)

一个容易忽视的点：AI 调用必须能降级。我给每个 AI 环节都设了开关和超时——查询改写失败就用原查询，rerank 超时就用向量原始排序。这样即使模型服务波动，搜索功能也不会整体挂掉。第3天主要在跑评测：准备 120 条真实查询样本，对比新旧搜索的命中率。

效果：一本可以算清的账

上线后一个月的对比：

• 开发周期：原计划自建全链路约 3 周，实际 3 天完成主体功能，节省约 80% 的工期
• 搜索命中率(自建评测集)：关键词匹配约 41%,语义搜索约 78%
• 单次搜索成本：embedding + 改写 + 重排合计约 0.002 美元，月度增量成本不到 20 美元
• 维护时间：过去每次调整模型相关配置平均 2-4 小时，现在约 20 分钟

更重要的收益是用户行为：搜索使用率从上线前的约 15% 升到 47%,“找不到内容”类反馈基本消失。

给独立开发者的三条建议

1. 先统一入口，再谈模型。不要在业务代码里到处写模型名和 API 地址。一个统一网关让“换模型”从工程问题变成配置问题。
2. AI 环节都要有降级路径。搜索这种核心功能，任何一次模型超时都不应该让用户看到报错。
3. 评测集先于调优。没有评测集，你无法知道换模型、调参数到底是变好还是变坏。

如果想让第一步更简单，可以先在 ThisToken.AI 注册一个账号，用同一个 Key 和统一的 API 入口把 embedding、chat、rerank 模型都跑通：https://api.thistoken.ai/register ——对独立开发者来说，少维护一分基础设施，就多一分时间打磨产品本身。

---

想直接跑通示例？访问 https://api.thistoken.ai/register 注册 ThisToken.AI，获取 API Key 后即可开始。