feat(async-context-compression): release v1.4.0 with structure-aware grouping and session locking
- Introduced Atomic Message Grouping to prevent tool-calling corruption (Issue #56) - Implemented Tail Boundary Alignment for deterministic context truncation - Added per-chat asynchronous session locking to prevent duplicate background tasks - Enhanced summarization traceability with message IDs and names - Synchronized version and changelog across all documentation files - Optimized release-prep skill to remove redundant H1 titles Closes #56
This commit is contained in:
fujie
345
scripts/UPDATE_MECHANISM.md
Normal file
345
scripts/UPDATE_MECHANISM.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 🔄 部署脚本的更新机制 (Deployment Update Mechanism)
|
||||
|
||||
## 核心答案
|
||||
|
||||
✅ **是的，再次部署会自动更新！**
|
||||
|
||||
部署脚本采用**智能两阶段策略**：
|
||||
1. 🔄 **优先尝试更新** (UPDATE) — 如果插件已存在
|
||||
2. 📝 **自动创建** (CREATE) — 如果更新失败（插件不存在）
|
||||
|
||||
## 工作流程图
|
||||
|
||||
```
|
||||
运行部署脚本
|
||||
↓
|
||||
读取本地代码和元数据
|
||||
↓
|
||||
发送 UPDATE 请求到 OpenWebUI
|
||||
↓
|
||||
├─ HTTP 200 ✅
|
||||
│ └─ 插件已存在 → 更新成功！
|
||||
│
|
||||
└─ 其他状态代码 (404, 400 等)
|
||||
└─ 插件不存在或更新失败
|
||||
↓
|
||||
发送 CREATE 请求
|
||||
↓
|
||||
├─ HTTP 200 ✅
|
||||
│ └─ 创建成功！
|
||||
│
|
||||
└─ 失败
|
||||
└─ 显示错误信息
|
||||
```
|
||||
|
||||
## 详细步骤分析
|
||||
|
||||
### 步骤 1️⃣: 尝试更新 (UPDATE)
|
||||
|
||||
```python
|
||||
# 代码位置: deploy_filter.py 第 220-230 行
|
||||
|
||||
update_url = "http://localhost:3003/api/v1/functions/id/{filter_id}/update"
|
||||
|
||||
response = requests.post(
|
||||
update_url,
|
||||
headers=headers,
|
||||
data=json.dumps(payload),
|
||||
timeout=10,
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
print(f"✅ Successfully updated '{title}' filter!")
|
||||
return True
|
||||
```
|
||||
|
||||
**这一步**:
|
||||
- 向 OpenWebUI API 发送 **POST** 到 `/api/v1/functions/id/{filter_id}/update`
|
||||
- 如果返回 **HTTP 200**，说明插件已存在且成功更新
|
||||
- 包含的内容:
|
||||
- 完整的最新代码
|
||||
- 元数据 (title, version, author, description 等)
|
||||
- 清单信息 (manifest)
|
||||
|
||||
### 步骤 2️⃣: 若更新失败，尝试创建 (CREATE)
|
||||
|
||||
```python
|
||||
# 代码位置: deploy_filter.py 第 231-245 行
|
||||
|
||||
if response.status_code != 200:
|
||||
print(f"⚠️ Update failed with status {response.status_code}, "
|
||||
"attempting to create instead...")
|
||||
|
||||
create_url = "http://localhost:3003/api/v1/functions/create"
|
||||
res_create = requests.post(
|
||||
create_url,
|
||||
headers=headers,
|
||||
data=json.dumps(payload),
|
||||
timeout=10,
|
||||
)
|
||||
|
||||
if res_create.status_code == 200:
|
||||
print(f"✅ Successfully created '{title}' filter!")
|
||||
return True
|
||||
```
|
||||
|
||||
**这一步**:
|
||||
- 如果更新失败 (HTTP ≠ 200)，自动尝试创建
|
||||
- 向 `/api/v1/functions/create` 发送 **POST** 请求
|
||||
- 使用**相同的 payload**（代码、元数据都一样）
|
||||
- 如果创建成功，第一次部署到 OpenWebUI
|
||||
|
||||
## 实际使用场景
|
||||
|
||||
### 场景 A: 第一次部署
|
||||
|
||||
```bash
|
||||
$ python deploy_async_context_compression.py
|
||||
|
||||
📦 Deploying filter 'Async Context Compression' (version 1.3.0)...
|
||||
File: .../async_context_compression.py
|
||||
⚠️ Update failed with status 404, attempting to create instead... ← 第一次，插件不存在
|
||||
✅ Successfully created 'Async Context Compression' filter! ← 创建成功
|
||||
```
|
||||
|
||||
**发生的事**:
|
||||
1. 尝试 UPDATE → 失败 (HTTP 404 — 插件不存在)
|
||||
2. 自动尝试 CREATE → 成功 (HTTP 200)
|
||||
3. 插件被创建到 OpenWebUI
|
||||
|
||||
---
|
||||
|
||||
### 场景 B: 再次部署 (修改代码后)
|
||||
|
||||
```bash
|
||||
# 第一次修改代码，再次部署
|
||||
$ python deploy_async_context_compression.py
|
||||
|
||||
📦 Deploying filter 'Async Context Compression' (version 1.3.1)...
|
||||
File: .../async_context_compression.py
|
||||
✅ Successfully updated 'Async Context Compression' filter! ← 直接更新！
|
||||
```
|
||||
|
||||
**发生的事**:
|
||||
1. 读取修改后的代码
|
||||
2. 尝试 UPDATE → 成功 (HTTP 200 — 插件已存在)
|
||||
3. OpenWebUI 中的插件被更新为最新代码
|
||||
4. **无需重启 OpenWebUI**，立即生效！
|
||||
|
||||
---
|
||||
|
||||
### 场景 C: 多次快速迭代
|
||||
|
||||
```bash
|
||||
# 第1次修改
|
||||
$ python deploy_async_context_compression.py
|
||||
✅ Successfully updated 'Async Context Compression' filter!
|
||||
|
||||
# 第2次修改
|
||||
$ python deploy_async_context_compression.py
|
||||
✅ Successfully updated 'Async Context Compression' filter!
|
||||
|
||||
# 第3次修改
|
||||
$ python deploy_async_context_compression.py
|
||||
✅ Successfully updated 'Async Context Compression' filter!
|
||||
|
||||
# ... 无限制地重复 ...
|
||||
```
|
||||
|
||||
**特点**:
|
||||
- 🚀 每次更新只需 5 秒
|
||||
- 📝 每次都是增量更新
|
||||
- ✅ 无需重启 OpenWebUI
|
||||
- 🔄 可以无限制地重复
|
||||
|
||||
## 更新的内容清单
|
||||
|
||||
每次部署时，以下内容会被更新：
|
||||
|
||||
✅ **代码** — 全部最新的 Python 代码
|
||||
✅ **版本号** — 从 docstring 自动提取
|
||||
✅ **标题** — 插件的显示名称
|
||||
✅ **作者信息** — author, author_url
|
||||
✅ **描述** — plugin description
|
||||
✅ **元数据** — funding_url, openwebui_id 等
|
||||
|
||||
❌ **配置不会被覆盖** — 用户在 OpenWebUI 中设置的 Valves 配置保持不变
|
||||
|
||||
## 版本号管理
|
||||
|
||||
### 更新时版本号会变吗？
|
||||
|
||||
✅ **是的，会变！**
|
||||
|
||||
```python
|
||||
# async_context_compression.py 的 docstring
|
||||
|
||||
"""
|
||||
title: Async Context Compression
|
||||
version: 1.3.0
|
||||
"""
|
||||
```
|
||||
|
||||
**每次部署时**:
|
||||
1. 脚本从 docstring 读取版本号
|
||||
2. 发送给 OpenWebUI 的 manifest 包含这个版本号
|
||||
3. 如果代码中改了版本号，部署时会更新到新版本
|
||||
|
||||
**最佳实践**:
|
||||
```bash
|
||||
# 1. 修改代码
|
||||
vim async_context_compression.py
|
||||
|
||||
# 2. 更新版本号（在 docstring 中）
|
||||
# 版本: 1.3.0 → 1.3.1
|
||||
|
||||
# 3. 部署
|
||||
python deploy_async_context_compression.py
|
||||
|
||||
# 结果: OpenWebUI 中显示版本 1.3.1
|
||||
```
|
||||
|
||||
## 部署失败的情况
|
||||
|
||||
### 情况 1: 网络错误
|
||||
|
||||
```bash
|
||||
❌ Connection error: Could not reach OpenWebUI at localhost:3003
|
||||
Make sure OpenWebUI is running and accessible.
|
||||
```
|
||||
|
||||
**原因**: OpenWebUI 未运行或端口错误
|
||||
**解决**: 检查 OpenWebUI 是否在运行
|
||||
|
||||
### 情况 2: API 密钥无效
|
||||
|
||||
```bash
|
||||
❌ Failed to update or create. Status: 401
|
||||
Error: {"error": "Unauthorized"}
|
||||
```
|
||||
|
||||
**原因**: .env 中的 API 密钥无效或过期
|
||||
**解决**: 更新 `.env` 文件中的 api_key
|
||||
|
||||
### 情况 3: 服务器错误
|
||||
|
||||
```bash
|
||||
❌ Failed to update or create. Status: 500
|
||||
Error: Internal server error
|
||||
```
|
||||
|
||||
**原因**: OpenWebUI 服务器内部错误
|
||||
**解决**: 检查 OpenWebUI 日志
|
||||
|
||||
## 设置版本号的最佳实践
|
||||
|
||||
### 语义化版本 (Semantic Versioning)
|
||||
|
||||
遵循 `MAJOR.MINOR.PATCH` 格式：
|
||||
|
||||
```python
|
||||
"""
|
||||
version: 1.3.0
|
||||
│ │ │
|
||||
│ │ └─ PATCH: Bug 修复 (1.3.0 → 1.3.1)
|
||||
│ └────── MINOR: 新功能 (1.3.0 → 1.4.0)
|
||||
└───────── MAJOR: 破坏性变更 (1.3.0 → 2.0.0)
|
||||
"""
|
||||
```
|
||||
|
||||
**例子**:
|
||||
|
||||
```python
|
||||
# Bug 修复 (PATCH)
|
||||
version: 1.3.0 → 1.3.1
|
||||
|
||||
# 新功能 (MINOR)
|
||||
version: 1.3.0 → 1.4.0
|
||||
|
||||
# 重大更新 (MAJOR)
|
||||
version: 1.3.0 → 2.0.0
|
||||
```
|
||||
|
||||
## 完整的迭代工作流
|
||||
|
||||
```bash
|
||||
# 1. 首次部署
|
||||
cd scripts
|
||||
python deploy_async_context_compression.py
|
||||
# 结果: 创建插件 (第一次)
|
||||
|
||||
# 2. 修改代码
|
||||
vim ../plugins/filters/async-context-compression/async_context_compression.py
|
||||
# 修改内容...
|
||||
|
||||
# 3. 再次部署 (自动更新)
|
||||
python deploy_async_context_compression.py
|
||||
# 结果: 更新插件 (立即生效，无需重启 OpenWebUI)
|
||||
|
||||
# 4. 重复步骤 2-3，无限次迭代
|
||||
# 每次修改 → 每次部署 → 立即测试 → 继续改进
|
||||
```
|
||||
|
||||
## 自动更新的优势
|
||||
|
||||
| 优势 | 说明 |
|
||||
|-----|------|
|
||||
| ⚡ **快速迭代** | 修改代码 → 部署 (5秒) → 测试，无需等待 |
|
||||
| 🔄 **自动检测** | 无需手动判断是创建还是更新 |
|
||||
| 📝 **版本管理** | 版本号自动从代码提取 |
|
||||
| ✅ **无需重启** | OpenWebUI 无需重启，配置保持不变 |
|
||||
| 🛡️ **安全更新** | 用户配置 (Valves) 不会被覆盖 |
|
||||
|
||||
## 禁用自动更新? ❌
|
||||
|
||||
通常**不需要**禁用自动更新，因为：
|
||||
|
||||
1. ✅ 更新是幂等的 (多次更新相同代码 = 无变化)
|
||||
2. ✅ 用户配置不会被修改
|
||||
3. ✅ 版本号自动管理
|
||||
4. ✅ 失败时自动回退
|
||||
|
||||
但如果真的需要控制，可以：
|
||||
- 手动修改脚本 (修改 `deploy_filter.py`)
|
||||
- 或分别使用 UPDATE/CREATE 的具体 API 端点
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 更新是否会丢失用户的配置？
|
||||
|
||||
❌ **不会！**
|
||||
用户在 OpenWebUI 中设置的 Valves (参数配置) 会被保留。
|
||||
|
||||
### Q: 是否可以回到旧版本？
|
||||
|
||||
✅ **可以！**
|
||||
修改代码中的 `version` 号为旧版本，然后重新部署。
|
||||
|
||||
### Q: 更新需要多长时间？
|
||||
|
||||
⚡ **约 5 秒**
|
||||
包括: 读文件 (1s) + 发送请求 (3s) + 响应 (1s)
|
||||
|
||||
### Q: 可以同时部署多个插件吗？
|
||||
|
||||
✅ **可以！**
|
||||
```bash
|
||||
python deploy_filter.py async-context-compression
|
||||
python deploy_filter.py folder-memory
|
||||
python deploy_filter.py context_enhancement_filter
|
||||
```
|
||||
|
||||
### Q: 部署失败了会怎样？
|
||||
|
||||
✅ **OpenWebUI 中的插件保持不变**
|
||||
失败不会修改已部署的插件。
|
||||
|
||||
---
|
||||
|
||||
**总结**: 部署脚本的更新机制完全自动化，开发者只需修改代码，每次运行 `deploy_async_context_compression.py` 就会自动：
|
||||
1. ✅ 创建（第一次）或更新（后续）插件
|
||||
2. ✅ 从代码提取最新的元数据和版本号
|
||||
3. ✅ 立即生效，无需重启 OpenWebUI
|
||||
4. ✅ 保留用户的配置不变
|
||||
|
||||
这使得本地开发和快速迭代变得极其流畅！🚀
|
||||
Reference in New Issue
Block a user