企业官网建设流程全解析

1. 项目概述：hindsight 是什么？它解决的不是技术问题，而是认知断层

hindsight 这个名字乍看像哲学概念，但放在当前 LLM 工具链语境里，它指的是一套面向大模型应用开发者的可观测性与调试基础设施——不是模型本身，也不是 API 封装库，而是在 OpenAI、DeepSeek、智谱、OpenRouter 等多源 LLM 接口之上，构建的一层“回溯式日志中枢”。它的核心价值，不在于让请求更快，而在于让失败可解释、让调用可复盘、让 prompt 工程有据可依。

我第一次在团队内部看到它被用起来，是在一个医疗知识问答系统上线后第三天。用户反馈“为什么同一个问题，上午回答准确，下午突然胡说八道？”——当时我们只留了 application 层日志，查不到 LLM 的实际输入输出、temperature 设置、token 截断位置、甚至不知道请求到底发给了哪家 provider。运维同学翻了两小时 Nginx access log，最后靠抓包才确认是 OpenRouter 的 fallback 路由把请求导到了一个低质量模型上。hindsight 就是为这种场景而生的：它不替代你的 LLM 调用逻辑，而是像给每条 API 请求装上黑匣子+行车记录仪——记录 request payload、response body、headers、耗时、token 统计、错误堆栈，甚至能还原出被截断的长 context 原始片段。

它和普通日志系统的本质区别在于语义感知能力：能自动识别并结构化提取messages数组中的 role/user/assistant 分段；能解析 streaming response 的 chunk 流并合并成完整 content；能根据 status code + error message 自动归类失败类型（比如401 unauthorized: incorrect api key provided: sk-svcac****这类报错，hindsight 会脱敏 key 后标记为 “AuthKeyInvalid”，而不是笼统记作 “HTTP 401”）；还能关联同一 session 下的多次调用，还原出完整的 multi-turn 对话链路。这使得它天然适配 LLM 应用的三大高频痛点：prompt 调试难、provider 切换混乱、token 成本不可控。

对开发者而言，hindsight 不是必须项，但一旦你开始做以下任何一件事，它就从“可选”变成“刚需”：

• 需要对比不同模型（如 gpt-4-turbo vs. deepseek-v2）在同一 prompt 下的输出差异；
• 正在搭建 LLM 网关或路由层，需要验证 fallback 逻辑是否按预期触发；
• 团队多人共用一套 API Key，需审计谁在什么时间调用了哪个模型、消耗了多少 token；
• 面临合规要求，需留存用户 query 与模型 response 的完整审计轨迹（注意：实际部署中需自行处理 PII 脱敏）；
• 在 Docker 环境中运行多个 LLM 服务（如 FastAPI + vLLM + Ollama），需要统一采集所有 outbound LLM 调用日志。

它不绑定特定框架，不强制使用某家云服务，也不要求修改业务代码——最轻量的接入方式，只需在你的 HTTP client 初始化时加一层 wrapper，或者在反向代理层（如 Nginx、Traefik）配置日志模块。但如果你选择用 Docker 部署，它就立刻显现出另一重价值：将分散在各容器中的 LLM 调用日志，通过标准协议（HTTP/WebSocket/Syslog）汇聚到单一可观测节点，避免在 5 个容器里分别 exec 进去 grep 日志的灾难。

所以别被名字迷惑——hindsight 不是“事后诸葛亮”，它是你在 LLM 应用开发现场，提前埋好的第一颗探针。

2. 整体架构设计：为什么不用 ELK 或 Datadog？三层解耦的务实选择

hindsight 的架构不是从零造轮子，而是针对 LLM 调用日志的特殊性做了精准裁剪。它没有照搬传统 APM（如 Datadog、New Relic）的全链路追踪模型，也没有采用 ELK（Elasticsearch + Logstash + Kibana）那种通用日志管道——因为 LLM 日志有三个强特征：高敏感性、强结构化、低写入频次但高单条体积。拿一条典型的 gpt-4-turbo 调用日志来说，仅messages数组就可能含 10KB+ 的 base64 编码图片描述，加上完整 response content，单条日志轻松突破 100KB。ELK 默认的 Logstash pipeline 在处理这种 payload 时极易 OOM，而 Datadog 的采样策略又会让关键 debug 信息被丢弃。

因此 hindsight 采用三层解耦设计：采集层 → 传输层 → 存储/查询层，每一层都针对 LLM 场景做了取舍。

2.1 采集层：无侵入式注入，支持三种接入模式

采集层的核心目标是“不改业务代码也能埋点”。它提供三种兼容方案，按侵入性由低到高排列：

1. 反向代理模式（推荐用于生产环境）：在 Nginx 或 Traefik 前置一层，所有 LLM API 请求先经过此代理。代理不做业务逻辑，只做三件事：① 记录原始 request headers/body；② 添加X-Hindsight-IDheader 透传至上游；③ 将 response body 复制一份发往 hindsight collector。这种方式零代码修改，且能捕获所有 outbound 请求（包括 curl、requests、甚至前端 fetch），缺点是需额外维护代理配置。

2. SDK Wrapper 模式（推荐用于开发调试）：提供 Python/Node.js SDK，封装主流 HTTP client。以 Python 为例，你只需把原来的：

import openai openai.api_key = "sk-..." response = openai.ChatCompletion.create(model="gpt-4", messages=[...])

替换成：

from hindsight import HindsightOpenAI client = HindsightOpenAI(api_key="sk-...", collector_url="http://localhost:8000") response = client.chat.completions.create(model="gpt-4", messages=[...])

SDK 内部会自动注入X-Hindsight-ID，捕获 request/response，并异步上报。它比代理模式更精确（能拿到 client-side 的 retry 次数、timeout 设置），但要求你控制所有 LLM 调用入口。

3. Docker Sidecar 模式（推荐用于多容器微服务）：为每个运行 LLM client 的容器，附加一个hindsight-collectorsidecar 容器。sidecar 通过共享 volume 或 Unix socket 监听业务容器的 stdout/stderr，用正则匹配识别 LLM API 调用日志（例如匹配"POST https://api.openai.com/v1/chat/completions"）。这种方式无需修改任何代码，也无需改网络拓扑，但依赖日志格式规范，精度略低于前两种。

提示：不要试图用logging.basicConfig()直接 hook root logger——LLM SDK（如 openai-python）内部会 suppress 或重定向日志，导致你捕获不到关键字段。hindsight 的 SDK wrapper 是唯一能稳定获取完整 request/response 的方式。

2.2 传输层：为什么放弃 Kafka，选择 HTTP + WebSocket 双通道？

传输层负责将采集到的日志安全、可靠地送达存储层。这里 hindsight 做了一个反直觉的选择：放弃 Kafka 这类高吞吐消息队列，改用 HTTP POST + WebSocket 长连接双通道。

理由很实在：Kafka 的优势在于百万级 QPS 的流式处理，而典型 LLM 应用的调用量远达不到这个量级（中小团队日均 1k~10k 次调用已是高负载）。引入 Kafka 带来的运维成本（ZooKeeper 集群、Topic 管理、Consumer Group 协调）远超收益。更关键的是，Kafka 的 at-least-once 语义会导致日志重复——而 LLM 调试最怕重复日志干扰判断（比如一次失败重试被记为两次独立失败）。

所以 hindsight 采用双通道设计：

• HTTP POST 通道：用于传输结构化日志（JSON 格式），带idempotency-keyheader 实现幂等写入。每次请求生成 UUID 作为 key，collector 收到后先查 Redis 缓存，若已存在则直接返回 200，避免重复入库。
• WebSocket 通道：专用于实时 streaming 日志（如 OpenAI 的stream=Trueresponse）。HTTP 无法优雅处理 chunk 流，而 WebSocket 天然支持双向实时通信。collector 通过 WS 连接维持长会话，将每个 chunk 按序缓存，待data: [DONE]到达后合并为完整 response 并落库。

注意：WebSocket 通道需客户端主动建立连接并维持心跳。hindsight SDK 内置了自动重连机制（指数退避），但若你的业务容器频繁重启，需在 container lifecycle hook 中显式 close WS 连接，否则 collector 会堆积大量僵尸连接。

2.3 存储/查询层：SQLite 为何能扛住日均 10 万条 LLM 日志？

存储层是 hindsight 最具争议的设计——它默认使用SQLite作为主存储引擎，而非 PostgreSQL 或 Elasticsearch。

这并非偷懒，而是基于真实压测数据的务实选择。我们曾用真实生产流量（模拟 50 并发、平均响应 2s、单条日志 80KB）对三种存储做对比测试：

关键在于 SQLite 的 WAL（Write-Ahead Logging）模式：它允许多个 writer 并发写入，且写操作不阻塞读。hindsight 对 SQLite 做了两项关键优化：

• 启用PRAGMA journal_mode=WAL和PRAGMA synchronous=normal，牺牲极小的数据持久性（断电丢失最后 1s 数据）换取 3 倍写入性能；
• 使用json1扩展函数直接在 SQL 中解析 JSON 字段，例如：SELECT * FROM logs WHERE json_extract(payload, '$.error.code') = 'invalid_api_key'，无需预定义 schema。

当然，SQLite 不是银弹。当单日日志量超过 50 万条，或需要跨多月做复杂聚合（如“统计过去 30 天各模型的 avg_token_per_request”），我们就建议切换到 PostgreSQL。hindsight 提供无缝迁移脚本：hindsight-migrate --from sqlite --to postgresql，它会自动创建表结构、转换 JSON 字段、重建索引。

3. 核心细节解析：如何让 401 错误不再成为谜团？

hindsight 的真正价值，往往体现在那些让你抓狂的细节处理上。比如那条高频报错：unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****。表面看是密钥错了，但实际原因可能有五种：API Key 本身无效、Key 绑定的 Organization 被禁用、Rate Limit 超额导致临时封禁、Provider 的 Auth 服务区域性故障、甚至是你代码里拼错了 header 名字（Authorization: Bearer sk-xxx写成Authorization: bearer sk-xxx）。hindsight 如何帮你在 10 秒内定位真因？答案藏在它的错误解析引擎里。

3.1 错误归一化：把千奇百怪的报错翻译成标准语义

hindsight 不直接存储原始 error message，而是通过规则引擎将其映射到统一错误码体系。这套体系覆盖了 OpenAI、Anthropic、DeepSeek、Qwen、Ollama 等 12 家主流 provider，每种错误包含三个维度：

• Error Category（大类）：如Auth,RateLimit,ModelNotFound,ContextLengthExceeded,ServerError；
• Error Code（子码）：如AuthKeyInvalid,AuthOrgDisabled,RateLimitExceeded,ModelNotAvailableInRegion；
• Resolution Hint（解决提示）：非通用文案，而是具体操作指引，例如：
  • AuthKeyInvalid→ “检查 API Key 是否复制完整，确认未混入空格或换行符；验证 Key 是否在 provider 控制台处于 active 状态”；
  • RateLimitExceeded→ “查看响应 headers 中的x-ratelimit-remaining值；若为 0，等待x-ratelimit-reset指定的秒数后再试；考虑增加 retry-after 逻辑”。

这个映射不是硬编码，而是通过 YAML 规则文件定义，支持热更新。例如 OpenAI 的 401 错误规则片段：

openai: 401: - pattern: "incorrect api key provided" category: Auth code: AuthKeyInvalid hint: "Check if the API key is copied correctly without extra spaces or line breaks." - pattern: "you must be a member of an organization to use this endpoint" category: Auth code: AuthOrgDisabled hint: "Log in to platform.openai.com, go to Settings > Organization, and ensure your org is active."

实操心得：我们曾遇到一个诡异 case——同一份 Key，在 Postman 里能调通，但在 Python 代码里持续 401。hindsight 的错误解析显示AuthKeyInvalid，但 hint 提示检查空格。我们用repr(key)打印才发现，代码里 Key 字符串末尾有个不可见的\u200b（零宽空格）。这个细节，是任何通用日志系统都难以捕捉的。

3.2 Token 成本透视：不只是 count，而是理解“为什么这么贵”

LLM 开发者最痛的不是调不通，而是账单看不懂。hindsight 的 token 统计模块，不满足于调用tiktoken算个总数，而是拆解出三重成本：

1. Input Token Breakdown：区分system/user/assistant角色的 token 占比。例如你设了 2000 字的 system prompt，但实际只用了 300 token，其余被 truncation —— hindsight 会在日志中标记input_truncated: true并记录truncated_at: 300。

2. Output Token Context：不仅统计 response token 数，还关联分析max_tokens参数设置与实际生成长度的关系。如果max_tokens=100但 response 用了 98 token，说明模型几乎填满上限，可能暗示 prompt 过于开放；反之若只用 12 token，大概率是模型 early-stopped（如遇到\n\n或</s>）。

3. Embedding Cost Leakage：很多团队忽略 embedding 调用的成本。hindsight 会识别/embeddingsendpoint 请求，并单独标记is_embedding: true，避免它和 chat completion 混在一起统计。

这些数据最终汇聚成 dashboard 上的“Cost Heatmap”：横轴是日期，纵轴是 model name，单元格颜色深浅代表当日 token 成本密度（token/请求），鼠标悬停显示 top-3 高成本 prompt 摘要。我们用这个图发现过一个隐藏问题：某天gpt-4-turbo的平均 token/request 突然飙升 300%，排查后发现是前端上传的 PDF 解析结果未做 length limit，导致单次请求携带 50 页文本。

3.3 Docker 部署避坑：Virtualization Support Not Detected 的真相

提到 Docker，绕不开那个经典报错：Virtualization support not detected. Docker Desktop failed to start because...。网上教程大多教你开 BIOS 的 VT-x/AMD-V，但实际在 Windows 10/11 上，90% 的 case 根源是Windows Subsystem for Linux 2 (WSL2) 未正确安装或内核过旧。

hindsight 的 Docker Compose 部署包（docker-compose.yml）默认依赖 WSL2，因为它比 Hyper-V 更轻量，且能原生挂载 Windows 文件系统。但很多人卡在第一步：wsl --install后执行wsl -l -v显示Ubuntu-22.04版本是Kernel: 5.10.102.1，而 hindsight collector 要求 ≥5.15.0（因用到了 io_uring 新特性提升日志写入性能）。

解决方案分三步：

1. 更新 WSL2 内核：访问 https://learn.microsoft.com/en-us/windows/wsl/install-manual#downloading-distributions，下载最新wsl_update_x64.msi并安装；
2. 升级发行版内核：在 PowerShell 中运行wsl --update；
3. 重启 WSL：wsl --shutdown，再启动 Docker Desktop。

注意：不要试图用docker run -it --rm alpine uname -r查看内核版本——它显示的是容器内核，不是宿主机 WSL2 内核。正确命令是wsl -d Ubuntu-22.04 uname -r。

另一个常见陷阱是 volume 权限。hindsight 默认将 SQLite DB 挂载到./data/hindsight.db，但在 Windows 上，Docker Desktop 的 WSL2 backend 对 NTFS 文件权限处理异常，导致容器内进程无法写入 DB 文件。解决方案是：在docker-compose.yml中显式设置 user ID：

services: collector: image: hindsight/collector:latest volumes: - ./data:/app/data user: "1001:1001" # 匹配 WSL2 中 ubuntu 用户的 UID/GID

4. 实操过程：从零启动一个可调试的 LLM 服务

现在我们动手搭建一个最小可行环境：一个 FastAPI 服务，调用 OpenAI API，并通过 hindsight 实现全链路可观测。整个过程在 Windows 10/11 + Docker Desktop 下验证，耗时约 12 分钟。

4.1 环境准备：确认 WSL2 与 Docker Desktop 就绪

首先验证基础环境：

# 检查 WSL2 状态 wsl -l -v # 输出应类似： # NAME STATE VERSION # * Ubuntu-22.04 Running 2 # 检查 Docker Desktop docker version --format '{{.Server.Version}}' # 应输出 ≥ 24.0.0 # 检查 Docker 是否能访问 WSL2 docker run --rm hello-world # 若报错 "Cannot connect to the Docker daemon"，重启 Docker Desktop

若wsl -l -v显示STATE: Stopped，运行wsl --shutdown后重启 Docker Desktop；若docker run失败，右键任务栏 Docker 图标 → “Troubleshoot” → “Reset to factory defaults”。

4.2 启动 hindsight collector：一行命令搞定

hindsight 官方镜像已发布到 Docker Hub，无需 clone 仓库：

# 创建数据目录（Windows PowerShell） mkdir .\hindsight-data # 启动 collector（后台运行） docker run -d \ --name hindsight-collector \ -p 8000:8000 \ -v ${PWD}/hindsight-data:/app/data \ -e DATABASE_URL=sqlite:///app/data/hindsight.db \ -e LOG_LEVEL=INFO \ -e COLLECTOR_PORT=8000 \ hindsight/collector:latest

验证是否启动成功：

curl http://localhost:8000/health # 返回 {"status": "ok", "timestamp": "2024-06-15T10:20:30Z"}

提示：首次启动会自动初始化 SQLite DB 并创建表结构。若看到sqlite3.OperationalError: no such table: logs，说明容器启动太快，DB 还没建好，等 5 秒再试。

4.3 构建 LLM 服务：FastAPI + hindsight SDK

创建项目目录llm-service，新建main.py：

from fastapi import FastAPI, HTTPException from pydantic import BaseModel from hindsight import HindsightOpenAI import os app = FastAPI() # 初始化 hindsight client（指向本地 collector） hindsight_client = HindsightOpenAI( api_key=os.getenv("OPENAI_API_KEY"), collector_url="http://host.docker.internal:8000" # 注意：Windows Docker Desktop 用 host.docker.internal ) class ChatRequest(BaseModel): messages: list model: str = "gpt-3.5-turbo" @app.post("/chat") async def chat(request: ChatRequest): try: response = hindsight_client.chat.completions.create( model=request.model, messages=request.messages, temperature=0.7 ) return {"response": response.choices[0].message.content} except Exception as e: raise HTTPException(status_code=500, detail=str(e))

创建requirements.txt：

fastapi==0.111.0 uvicorn==0.29.0 hindsight-sdk==0.4.2 openai==1.35.0

4.4 Dockerize 服务：解决 host.docker.internal 兼容性

Windows 上host.docker.internal在 Docker Desktop 4.18+ 才原生支持。为兼容旧版本，我们在docker-compose.yml中显式添加 network alias：

version: '3.8' services: llm-service: build: . ports: - "8001:8000" environment: - OPENAI_API_KEY=${OPENAI_API_KEY} extra_hosts: - "host.docker.internal:host-gateway" # 关键：让容器内能解析 host.docker.internal depends_on: - hindsight-collector hindsight-collector: image: hindsight/collector:latest ports: - "8000:8000" volumes: - ./hindsight-data:/app/data environment: - DATABASE_URL=sqlite:///app/data/hindsight.db

构建并启动：

# 设置环境变量（PowerShell） $env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" docker compose up -d --build

4.5 发起测试请求并验证日志采集

用 curl 发送测试请求：

curl -X POST http://localhost:8001/chat \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "用一句话解释量子纠缠"}], "model": "gpt-3.5-turbo" }'

然后检查 hindsight 日志：

# 进入 collector 容器 docker exec -it hindsight-collector sh # 查询最近一条日志（SQLite CLI） sqlite3 /app/data/hindsight.db "SELECT id, created_at, model, status_code, input_tokens, output_tokens FROM logs ORDER BY created_at DESC LIMIT 1;" # 输出示例： # 123|2024-06-15 10:25:30.123|gpt-3.5-turbo|200|42|67

更直观的方式是访问 Web UI（默认开启）：打开 http://localhost:8000/ui，你会看到实时日志流，点击任意条目可展开完整 request/response JSON。

实操心得：第一次测试时，我们发现日志里status_code总是0。排查发现是 FastAPI 的HTTPException被hindsight_client捕获后，未正确传递 response status。解决方案是在main.py中 catch OpenAIError 并 re-raise：

from openai import OpenAIError try: response = ... except OpenAIError as e: # hindsight 已记录 error，此处抛出便于 FastAPI 返回 500 raise HTTPException(status_code=500, detail=f"LLM Error: {str(e)}")

5. 常见问题与排查技巧实录：那些文档里不会写的坑

在 37 个客户部署 hindsight 的过程中，我们整理出一份高频问题清单。这些问题大多源于 LLM 生态的碎片化现状，而非 hindsight 本身缺陷。以下按发生频率排序，每条都附真实案例和独家解法。

5.1 问题速查表：快速定位你的症状

5.2 深度案例：为什么unexpected status 401有时是 DNS 问题？

这是最反直觉的案例。某金融客户报告：生产环境每天固定时段（早 9:00）出现批量 401，持续 5 分钟，之后自动恢复。他们确认 Key 有效，且其他时段正常。

我们让客户在 collector 容器内执行：

# 模拟 OpenAI 请求的 DNS 解析 docker exec hindsight-collector nslookup api.openai.com # 输出： # Server: 127.0.0.11 # Address: 127.0.0.11#53 # ** server can't find api.openai.com: NXDOMAIN

问题根源浮出水面：客户使用了自建 DNS 服务器，该服务器在每日凌晨 2:00 执行 zone transfer，期间短暂返回 NXDOMAIN。而 OpenAI SDK 的默认 DNS timeout 是 5s，超时后直接返回401 unauthorized（因请求根本没发出，SDK 错误地将网络层失败映射为 auth 失败）。

解决方案有二：

• 短期：在docker-compose.yml中为 collector 指定可靠 DNS：

  services: hindsight-collector: dns: - 8.8.8.8 - 1.1.1.1

• 长期：升级 OpenAI SDK 至 ≥ 1.30.0，它已修复 DNS timeout 的错误映射逻辑，改为抛出openai.APIConnectionError。

注意：这个案例说明，hindsight 的价值不仅是“看到错误”，更是提供上下文证据链——没有它，你只会看到一堆 401，永远想不到去查 DNS。

5.3 独家技巧：用 hindsight 日志反向生成测试用例

hindsight 的结构化日志，本身就是绝佳的测试数据源。我们开发了一个小工具hindsight-fuzzer，能从历史日志中自动提取：

• 高频失败的 prompt 模板（如含特定关键词的 user message）；
• 导致 token 超限的 context 边界（如input_tokens > 8000的样本）；
• 多模型对比的黄金标准输出（model=gpt-4的 response 作为 ground truth）。

用法示例：

# 生成 10 个导致 400 错误的 prompt 测试集 hindsight-fuzzer --db hindsight.db \ --filter "status_code=400 AND provider='openai'" \ --output test_prompts.json \ --count 10 # 生成 token 压力测试脚本 hindsight-fuzzer --db hindsight.db \ --filter "input_tokens > 10000" \ --mode stress \ --output stress_test.py

这个技巧让我们的 QA 团队效率提升 3 倍——不再靠人工构造边界 case，而是用真实生产数据驱动测试。

5.4 终极警告：关于sk-svcac****这类 Key 泄露的处理

在日志中看到sk-svcac****这样的 Key 片段，第一反应是惊慌。但 hindsight 的设计原则是：日志系统绝不应成为密钥泄露的放大器。

默认情况下，hindsight 会对所有 API Key 做确定性脱敏：取 Key 前缀 8 位 +****+ 后缀 4 位，例如sk-svcac1234567890abcdef1234567890→sk-svcac****5678。这个脱敏是 irreversible 的（使用 SHA256 hash salted 后截取），即使数据库被拖库，也无法还原原始 Key。

但如果你在日志中看到完整 Key，一定是以下原因之一：

• 你手动关闭了脱敏：hindsight-client --no-sanitize-key；
• 你用了自定义 logging handler，绕过了 SDK 的脱敏逻辑；
• 你的业务代码在 exception message 中硬编码了 Key（如f"API call failed: {key}"）。

提示：永远不要在 error message 中拼接敏感信息。正确的做法是：

# ❌ 危险 raise Exception(f"Auth failed for key {os.getenv('OPENAI_API_KEY')}") # ✅ 安全 raise Exception("Auth failed for configured API key")

hindsight 无法保护你代码里的低级错误，但它提供了最后一道防线——只要启用默认配置，你的 Key 就是安全的。

6. 进阶场景：hindsight 如何支撑 LLM Wiki 知识库建设？

LLM Wiki 知识库（LLM-Wiki）是当前企业级 LLM 应用的热点方向——它不是简单地把文档喂给向量库，而是构建一个动态演化的、带版本控制的、可追溯决策链的知识中枢。hindsight 在其中扮演“知识血缘追踪器”的角色。

6.1 知识入库阶段：确保 source 可信

LLM-Wiki 的第一条铁律是：任何知识片段必须标注可信来源。hindsight 通过source_id字段实现这一点。当你用 hindsight SDK 调用 embedding API 时：

# 上传一份 PDF 文档，生成 embedding response = hindsight_client.embeddings.create( input=["量子纠缠是量子力学的基本现象..."], model="text-embedding-3-small", metadata={"source_id": "doc-quantum-physics-v2.1.pdf", "page": 42} )

hindsight 会自动将metadata与 embedding 请求关联，并在日志中记录source_id。后续知识库检索时，系统可反向查询：哪些 embedding 来自doc-quantum-physics-v2.1.pdf？它们被哪些问答请求引用过？

6.2 知识推理阶段：暴露“幻觉”生成路径

当用户提问“公立医院债务风险化解策略”，LLM-Wiki 可能组合来自 3 份政策文件 + 1 份财报的片段。hindsight 记录的不只是最终 answer，而是完整的 RAG trace：

• retrieval_query: "公立医院 债务 风险 化解"
• retrieved_chunks:[{"id": "chunk-123", "score": 0.92}, ...]
• prompt_context: 拼接后的 context（含 source_id 标注）
• final_response: LLM 生成的答案

这样，当答案出现事实错误（如把“财政补贴”写成“税收减免”），审计员可回溯：是 retrieval 阶段漏掉了关键 chunk？还是 LLM 在 context 中曲解了原文？抑或是 prompt 指令有歧义？每一步都有迹可循。

6.3 知识迭代阶段：量化“知识衰减率”

知识不是静态的。一份 2022 年的医保政策，在 2024 年可能已失效。hindsight 通过knowledge_age_days字段量化这一衰减：

• 当source_id对应的文档被更新（如doc-quantum-physics-v3.0.pdf替代v2.1），新 embedding 的日志会标记knowledge_age_days=0；
• 旧 embedding 被引用时，日志自动计算 `age = now - document_update