revazi/django-asklens

# Django AskLens [](https://pypi.org/project/django-asklens/) [](https://pypi.org/project/django-asklens/) Django AskLens 是一个可复用的 Django 包，用于在显式注册的 Django 模型上进行安全的自然语言查询，并支持可选的 Django REST Framework API 集成。 AskLens **不**允许 LLM 编写 SQL。它会向 provider 请求结构化的 JSON，根据您注册的目录和权限验证计划，编译只读的 Django ORM 查询，在限制下执行，并返回适用于表格/图表的 JSON。 状态：**alpha**。API 在稳定版本发布之前可能会发生更改。 ## 它提供的功能 - 显式的语义资源注册。 - 权限范围的目录和功能元数据。 - 可选的 DRF 目录、功能、查询和运行详情 endpoint。 - 严格的 Pydantic `QueryPlan` 验证。 - 仅限 ORM 的列表和聚合查询执行。 - 用于确定性测试和演示的 Dummy provider。 - 兼容 OpenAI 的实时 provider 适配器。 - 查询运行审计记录。 - 与前端无关的 `columns` + `data` JSON 输出。 - 可选的打包浏览器 UI，用于演示/参考。 ## 快速开始 从 [PyPI](https://pypi.org/project/django-asklens/) 安装： ``` python -m pip install 'django-asklens[api]' ``` 添加 DRF 和 AskLens 应用： ``` INSTALLED_APPS = [ # ... "rest_framework", "django_asklens", ] ``` 挂载 API： ``` from django.urls import include, path urlpatterns = [ path("", include("django_asklens.api.urls")), ] ``` 为 AskLens 审计记录运行迁移： ``` python -m django migrate asklens ``` 在应用启动期间注册资源： ``` from django_asklens import Metric, register from shop.models import Order def visible_orders(request): if not getattr(request.user, "is_authenticated", False): return Order.objects.none() return Order.objects.filter(account__memberships__user=request.user) register( model=Order, name="orders", label="Orders", description="Orders visible to the current user.", default_date_field="created_at", fields={ "id": {"label": "Order ID"}, "status": {"label": "Status"}, "created_at": {"label": "Created date"}, "customer.email": { "label": "Customer email", "sensitive": True, "requires_permission": "customers.view_pii", }, "total_cents": {"label": "Total in cents"}, }, metrics=[ Metric("order_count", op="count", field="id", label="Orders"), Metric("revenue", op="sum", field="total_cents", label="Revenue"), ], requires_permission="orders.view_reports", base_queryset=visible_orders, ) ``` 资源上的 `requires_permission` 控制整个资源的目录可见性和查询验证。字段级别的 `requires_permission` 控制单个字段（例如 PII）。 从确定性的 dummy provider 开始： ``` DJANGO_ASKLENS = { "LLM_BACKEND": "dummy", "DUMMY_PLANS": { "Show orders by status": { "resource": "orders", "intent": "aggregate", "group_by": [{"field": "status"}], "metrics": [{"name": "order_count", "op": "count", "field": "id"}], "limit": 100, "visualization": {"type": "bar", "x": "status", "y": "order_count"}, } }, } ``` 通过 API 进行提问： ``` POST /asklens/query/ Content-Type: application/json {"question": "Show orders by status"} ``` 成功的数据响应包括： ``` { "run_id": 1, "question": "Show orders by status", "response_type": "query", "plan": {"resource": "orders", "intent": "aggregate", "limit": 100}, "columns": [{"key": "status", "label": "Status", "type": "string"}], "data": [{"status": "paid", "order_count": 12}], "row_count": 1, "result_metadata": { "limit": 100, "limit_scope": "groups", "limit_reached": false }, "visualization": {"type": "bar"} } ``` 诸如 `show me example queries` 的帮助问题会返回 `response_type: "capabilities"` 并提供建议，而不会运行数据库查询。 ## 构建 UI 当通过 `api` 扩展安装时，AskLens 是 API 优先的。您可以通过渲染返回的 `columns` 和 `data` 数组，使用 React、Vue、HTMX、Django 模板、移动客户端或任何图表/表格库来构建自己的 UI。 打包的前端是可选的，旨在作为无依赖的演示/参考 UI。需要特定产品布局、图表、保存的查询或工作流的项目应直接调用 API。请参阅[构建自定义 AskLens UI](docs/custom-ui.md)。 ## 可选的打包前端 如果您想使用内置的参考 UI，请安装 `api` 扩展并挂载 API 和前端 URL： ``` urlpatterns = [ path("", include("django_asklens.api.urls")), path("", include("django_asklens.frontend.urls")), # /asklens/ui/ ] ``` 使用以下命令为选定的用户设置页面访问权限： ``` DJANGO_ASKLENS = { "FRONTEND_PERMISSION_CHECK": "myapp.permissions.can_use_asklens_frontend", } ``` API 路由权限仍然适用于每次 API 调用。前端权限检查仅控制打包页面是否可以加载。 ## 实时 provider 默认后端是 `dummy`，不会进行任何网络调用。要使用兼容 OpenAI 的 provider： ``` import os DJANGO_ASKLENS = { "LLM_BACKEND": "openai_compatible", "LLM_BASE_URL": "https://api.openai.com/v1", "LLM_API_KEY": os.environ["OPENAI_API_KEY"], "LLM_MODEL": "gpt-4.1-mini", "LLM_TEMPERATURE": 0, } ``` Gemini 可以通过其兼容 OpenAI 的 endpoint 使用： ``` DJANGO_ASKLENS = { "LLM_BACKEND": "openai_compatible", "LLM_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai", "LLM_API_KEY": os.environ["GEMINI_API_KEY"], "LLM_MODEL": "gemini-2.5-flash", "LLM_TEMPERATURE": 0, } ``` 实时 provider 测试是可选的，默认跳过。请参阅[Provider 配置](docs/providers.md)。 ## 安全姿态 - 只有显式注册的资源和字段是可查询的。 - 每个查询都从资源 `base_queryset(request)` 钩子开始。 - 敏感字段会被隐藏，除非被显式授予权限。 - Provider 的输出是不可信的，在执行前始终会进行验证。 - AskLens 仅执行只读的 Django ORM 查询。 - AskLens 不执行 LLM 生成的 SQL。 - AskLens 不会创建、更新或删除应用程序数据。 - 默认情况下，AskLens 不会向 provider 发送数据库行、样本值、机密信息、凭据或 `.env` 内容。 - 查询运行会被审计。 在本地开发之外启用 AskLens 之前，请查阅[安全检查清单](docs/security-checklist.md)和[生产环境检查清单](docs/production-checklist.md)。 ## Alpha 范围和安全边界 - API 在稳定版本发布之前可能会发生更改。 - AskLens 支持对显式注册的资源进行只读列表和聚合问题查询。 - 查询质量取决于清晰的资源、字段、描述和指标注册。 - 实时 provider 的行为因模型和 prompt 的复杂性而异；`DummyProvider` 仍然是用于测试和演示的确定性默认选项。 - SQL 生成/执行故意不在范围之内。AskLens 仅使用经过验证的 QueryPlan JSON 和 Django ORM 编译。 - 写入和修改故意不在范围之内。 - 服务端保存的查询、仪表板构建器和专用的帮助 endpoint 不是 alpha 包的一部分。 - 打包的前端是一个参考/演示 UI；自定义产品 UI 应直接调用 API。 - 只读副本/数据库路由是 alpha 阶段宿主项目的部署关注点。 - 当前的包元数据和 CI 针对 Django 5.2 LTS 和 Django 6.x。 ## 文档 - [安装](docs/installation.md) - [使用指南](docs/usage.md) - [核心 Python API](docs/core-python-api.md) - [自定义 UI 指南](docs/custom-ui.md) - [注册 API](docs/registration.md) - [Provider 配置](docs/providers.md) - [贡献](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [安全检查清单](docs/security-checklist.md) - [生产环境检查清单](docs/production-checklist.md) - [多租户安全](docs/multitenancy-security.md) - [评估夹具](docs/evaluation.md) - [可运行的复杂测试项目](docs/test-project-demo.md) - [更新日志](CHANGELOG.md) ## 开发 使用 Python 3.12 或更高版本以及 [`uv`](https://docs.astral.sh/uv/) 进行本地开发。开发依赖组包含 DRF，以便 API 集成测试在本地运行。 ``` uv sync --group dev uv run pytest uv run ruff check . uv run ruff format --check . ``` 该包保持基于标准并由 setuptools 提供支持；`uv` 用于贡献者工作流，而不是作为运行时依赖项。

标签：Django, DLL 劫持, Petitpotam, RESTful API, 大语言模型, 提示词优化, 自然语言查询, 逆向工具