nl_cache_framework | 通往MCP之路

NL Cache 框架

一个基于 Fastv1 构建的轻量级框架，用于管理自然语言查询缓存。

特性

创建、读取、更新和删除自然语言查询的缓存条目

将模板与查询关联

跟踪使用统计信息

简单的 REST API 接口

自动依赖安装

快速开始

前提条件

Python 3.8 或更高版本

安装

无需安装。运行应用程序时，它会自动安装所需的依赖项。

启动服务器

或者，如果你已经手动安装了依赖项并激活了环境：

服务器将启动在 http://localhost:8000。

API 端点

健康检查

返回服务器及其依赖项（如数据库）的健康状态。

处理自然语言查询

利用缓存处理自然语言提示。如果存在足够相似的查询，则返回缓存的模板/结果，否则表示缓存未命中。

请求体：

响应体（缓存命中）：

响应体（缓存未命中）：

搜索缓存条目

在缓存中搜索与提供的自然语言查询相似的条目。

查询参数：

nl_query（必填）：要搜索的自然语言查询。

template_type（可选）：按模板类型过滤（如 "sql", "url"）。

threshold（可选）：最小相似度分数（默认：0.7）。

limit（可选）：返回的最大结果数（默认：5）。

列出缓存条目

查询参数：

page：分页的页码（默认：1）

page_size：每页的条目数（默认：10）

search_query：可选搜索词，用于按 nl_query 或 template 内容过滤条目。

template_type：可选按模板类型过滤（如 "sql", "url", "api", "workflow"）。

创建缓存条目

请求体：请参阅下面的数据模型部分了解可能的字段。至少需要 nl_query 和 template。

获取缓存条目

按 ID 返回特定的缓存条目。

更新缓存条目

请求体：与创建端点的字段相同。仅包含需要更新的字段。

删除缓存条目

按 ID 删除缓存条目。

应用实体替换（测试）

使用提供的文本对模板条目应用实体替换。用于测试替换逻辑。

请求体：

测试缓存条目（实验性）

用于测试缓存条目特定功能的端点，可能与实体提取或替换相关。

获取缓存统计信息

返回缓存条目的统计信息，包括总数。注意：每个条目的使用次数现在单独跟踪。

数据模型 (`Text2SQLCache`)

每个缓存条目包含：

id：（整数）缓存条目的唯一标识符。

nl_query：（字符串）原始的自然语言查询。（必填）

template：（文本）与 NL 查询对应的模板（SQL、URL、API 规范等）。（必填）

template_type：（字符串）模板类型。默认为 sql。允许的值：sql, url, api, workflow。

vector_embedding：（向量）nl_query 的可选向量嵌入（例如用于相似性搜索）。

is_template：（布尔值）指示此条目是否包含用于实体替换的占位符的标志。默认为 false。

entity_replacements：（JSON）描述占位符及其替换类型的可选 JSON 对象。示例：{"entity_key": {"placeholder": ":placeholder_name", "type": "string"}}。

reasoning_trace：（文本）可选，解释模板是如何推导出来的。

tags：（JSON）用于分类的可选字符串列表（如 ["sales", "summary"]）。

suggested_visualization：（字符串）用于可视化结果的可选提示。

database_name：（字符串）目标数据库的可选标识符。

schema_name：（字符串）目标模式的可选标识符。

catalog_id：（整数）链接到外部数据目录的可选标识符。

is_valid：（布尔值）指示缓存条目当前是否有效的标志。默认为 true。

invalidation_reason：（字符串）条目被标记为无效的可选原因。

created_at：（DateTime）条目创建时的时间戳（UTC）。

updated_at：（DateTime）条目最后更新时间的时间戳（UTC）。

注意： 使用统计信息（如每个条目的命中次数）在单独的 UsageLog 表中跟踪，通过 cache_entry_id 链接。/v1/cache/stats 端点提供聚合统计信息。

开发

应用程序使用 SQLAlchemy，如果未配置外部数据库，则回退到内存中的 SQLite 数据库。

处理大文件

项目中使用了几个大型二进制文件，但为了控制仓库大小，这些文件被排除在版本控制之外。这些文件包括：

frontend/node_modules/@next/swc-darwin-arm64/next-swc.darwin-arm64.node

venv/lib/python3.11/site-packages/torch/lib/libtorch_cpu.dylib

venv/lib/python3.11/site-packages/torch/lib/libtorch_python.dylib

venv/lib/python3.11/site-packages/cryptography/hazmat/bindings/_rust.abi3.so

这些文件在设置开发环境时会自动生成，不应提交到仓库。.gitignore 文件已配置为排除这些文件。

设置新的开发环境时，请按照以下步骤操作：

克隆仓库

创建并激活虚拟环境：python -m venv venv && source venv/bin/activate

安装依赖项：pip install -r requirements.txt

设置前端：cd frontend && npm install

这将生成所有被排除在版本控制之外的必要二进制文件。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。