aidy.v2.plugin.semantic_cache

Messages

message SemanticCacheLog

请求日志中的 semantic cache 扩展字段。

message SemanticCacheLog {
    // 缓存处理状态，例如 hit / miss / bypass。
    string status = 1;
    // bypass 时的原因，例如 embedding_empty / embedding_failed / search_failed / store_failed。
    string bypass_reason = 2;
    // 命中时缓存条目的 ID。
    string cache_key = 3;
    // 命中时向量检索返回的距离（cosine 距离，0 表示完全一致）。
    double distance = 4;
    // 缓存命名空间 (sc:{tenant}:{route}:{model}:{tools_hash})。
    string namespace = 5;
    // Embedding 服务返回的 token 使用量。
    uint32 embedding_tokens = 6;
    // Embedding 服务调用耗时，单位毫秒。
    uint64 embedding_latency_ms = 7;
    // Redis 向量检索耗时，单位毫秒。
    uint64 search_latency_ms = 8;
    // 失败或异常时的错误信息。
    string error = 9;
    // 命中时缓存条目与请求向量的相似度（cosine 相似度，等于 1 - distance，越接近 1 越相似）。
    double similarity = 10;
    // 命中时缓存条目自写入到本次命中的存在时长，单位毫秒。
    uint64 cache_age_ms = 11;
}

message SemanticCachePluginConfig

路由级语义缓存配置。

message SemanticCachePluginConfig {
    // 缓存存活时间，单位秒。
    // 未显式设置时，运行时默认值为 300。
    uint32 cache_ttl_seconds = 1;
    // 相似度距离阈值。
    // 未显式设置时，运行时默认值为 0.15。
    float similarity_threshold = 2;
    // 距离度量方式，当前仅支持 cosine。
    // 未显式设置时，运行时默认值为 "cosine"。
    string distance_metric = 3;
    // 从末尾回看多少条匹配消息参与 embedding。
    // 未显式设置时，运行时默认值为 5。
    uint32 message_countback = 10;
    // 哪些 role 参与 embedding。
    // 未显式设置时，运行时默认值为 ["user"]。
    repeated string include_roles = 11;
    // 是否将 instructions 纳入 embedding 文本。
    // 未显式设置时，运行时默认值为 false。
    bool include_instructions = 12;
    // 是否将 tools 签名纳入命名空间隔离。
    // 未显式设置时，运行时默认值为 true。
    bool include_tools_signature = 13;
    // 是否按请求 model 隔离命名空间。
    // 未显式设置时，运行时默认值为 true。
    bool isolate_by_model = 14;
}