Add app_settings migration, settings UI, and OpenAI-compatible httpx LLM client with mocked tests. Preserve API keys on blank form submissions, require a fresh key when base_url changes, and keep AI search settings untouched for step 3. Update docs/design LLM integration and step 3 AI search notes, including prompt contract and extra-hints planning.
This commit is contained in:
@@ -199,6 +199,7 @@ More settings are coming; adding columns to an *existing* table costs a migratio
|
||||
| `llm_model` | 模型名 / model name | （空 / empty） |
|
||||
| `llm_api_key` | API Key（明文 / plaintext，见 §7） | （空 / empty） |
|
||||
| `ai_search_enabled` | AI 搜索功能开关 / AI-search feature toggle | `false` |
|
||||
| `ai_search_extra_hints` | AI 搜索：可选「额外领域提示」，追加到默认系统提示词（step 3 引入）/ optional extra domain hints appended to the default prompt | （空 / empty） |
|
||||
|
||||
> 读写封装 / Access helpers：`get_app_settings(db) -> LLMConfig`（dataclass 视图）与 `save_app_settings(db, ...)`，供路由与 `app/llm.py` 复用。
|
||||
> Helpers `get_app_settings(db) -> LLMConfig` and `save_app_settings(db, ...)`, reused by routes and `app/llm.py`.
|
||||
@@ -209,7 +210,7 @@ OpenAI 兼容的薄客户端，基于 `httpx`，**无新依赖** / A thin OpenAI
|
||||
|
||||
- `is_configured(cfg) -> bool`：开关开启且 `model`/`api_key` 齐全。
|
||||
- `test_connection(cfg) -> Result`：发一个最小请求验证 `base_url`/`model`/`api_key`，供配置页"测试连接"用。
|
||||
- `expand_query(cfg, query) -> list[str]`：把查询词扩成一批近义/相关词（本轮 AI 搜索用，见 §5）。
|
||||
- `expand_query(cfg, query) -> list[str]`：把查询词扩成一批近义/相关词（提示词与输出契约见 §5.2）。
|
||||
- `analyze_image(...)`：**本轮不实现**，仅在文档中预留为未来接口（图片分析轮次）。Reserved for a future round, not implemented now.
|
||||
|
||||
要点 / Notes：
|
||||
@@ -251,7 +252,22 @@ When disabled/unconfigured: the settings page still works; the AI-search button
|
||||
- **只把查询词发出去 / Only the query leaves**，不外泄物品清单；token 恒定、不随上千件物品增长。
|
||||
Only the query is sent; the inventory is not. Token cost is constant and does not grow with thousands of items.
|
||||
|
||||
### 5.2 实现接口 / Implementation seam
|
||||
### 5.2 提示词与输出契约 / Prompt & Output Contract
|
||||
|
||||
`expand_query` 的**质量**取决于提示词，**集成稳定性**取决于输出契约——两者都在代码侧掌控（决策 C）。
|
||||
Quality hinges on the prompt; integration stability hinges on the output contract — both are code-controlled (decision C).
|
||||
|
||||
- **基础系统提示词写死在 `app/llm.py`（用户改不坏）/ Base system prompt hardcoded：** 框定搬家/家居场景，要求"列出用户可能用来命名同一物品的相关词（近义、别称、上位类别、具体品类）"；语言跟随查询；最多约 8 个；不解释、不造无关词。
|
||||
Frames the moving/household domain, asks for related naming terms, follows the query's language, caps the count, no prose.
|
||||
- **可选「额外领域提示」/ Optional extra hints：** KV `ai_search_extra_hints`（设置页一个多行输入，默认空）。非空时**追加**到基础提示词之后，供业主微调倾向（如"厨房用品多，偏向厨具类"）。**它只能补充，不能改写输出格式。**
|
||||
An optional free-text setting appended to the base prompt; it can only add guidance, never alter the output format.
|
||||
- **输出契约（代码强制，与提示词解耦）/ Output contract (code-enforced)：** 要求模型只返回 **JSON 字符串数组**；解析时去掉 ` ```json ` 围栏 → `json.loads` → 失败按行/逗号兜底 → 再不行返回 `[]`。`expand_query` 只返回扩展词；**原词由 `ai_search` 并入并去重**，数量在代码侧再封顶一次。
|
||||
Require a JSON string array; tolerant parse with fallbacks to `[]`. `ai_search` adds the original term and dedupes; the count is capped in code.
|
||||
- **客户端参数 / Client params：** 低 temperature、较小 max_tokens、设超时。Low temperature, small max_tokens, a timeout.
|
||||
- **措辞留松 / Wording left loose：** 默认提示词的具体字句可在 step-3 实测中迭代，不在文档里冻死。
|
||||
Exact default wording can be iterated during step-3 testing.
|
||||
|
||||
### 5.3 实现接口 / Implementation seam
|
||||
|
||||
- 路由层扩展现有 `GET /search`：增加 `ai=1` 触发位（如 `GET /search?q=锅&ai=1`），保持单页、可收藏、SSR 友好。
|
||||
Extend the existing `GET /search` with an `ai=1` trigger (e.g. `/search?q=…&ai=1`), staying single-page and bookmarkable.
|
||||
@@ -263,7 +279,7 @@ When disabled/unconfigured: the settings page still works; the AI-search button
|
||||
- 本轮检索范围＝`name` + `note`（`image_description` 本轮不存在）。
|
||||
Search scope this round = `name` + `note` (no `image_description` yet).
|
||||
|
||||
### 5.3 降级 / Degradation
|
||||
### 5.4 降级 / Degradation
|
||||
|
||||
AI 关闭/未配置 → 不显示按钮（或提示去 `/settings`）；调用失败 → 友好提示并回退到普通结果。
|
||||
AI off/unconfigured → no button (or a hint to `/settings`); on failure → a friendly message, fall back to normal results.
|
||||
@@ -334,3 +350,4 @@ AI off/unconfigured → no button (or a hint to `/settings`); on failure → a f
|
||||
| D8 | AI 搜索 v1＝查询词扩展 / query-term expansion | 上千件物品下可扩展、不外泄清单、token 恒定。 |
|
||||
| D9 | 检索做成可替换 seam / pluggable retrieval | 未来换嵌入式语义搜索时上层不动。 |
|
||||
| D10 | 图片分析不在本轮 / image analysis deferred | 业主本轮三件事不含它；架构预留接口。 |
|
||||
| D11 | AI 搜索提示词：默认写死 + 可选「额外领域提示」；输出契约由代码强制 / hardcoded default prompt + optional extra-hints, code-enforced JSON contract | 保证解析稳定（用户改不坏），又给业主一点不改代码即可微调的空间。 |
|
||||
|
||||
Reference in New Issue
Block a user