v0.4.11

Release date / 发布日期: 2026-07-23

---

版本概览

OpenViking v0.4.11 是一个包含 45 个提交的维护与性能版本。该版本重点改进检索标签语义、cuVS 查询吞吐、飞书/Lark 资源导入和 Python SDK 可观测性，并集中修复资源队列、事务锁、会话上下文、解析器和 CLI 的可靠性问题。

主要更新

• 检索标签改为严格 AND 语义：find() 和 search() 的多个 tags 现在要求结果包含全部标签，REST API、Python SDK、CLI、本地客户端和 LangChain 集成保持一致。
• cuVS 支持可选的请求 micro-batching：兼容的 exact brute-force 查询可合并为一次 GPU matrix search；同时降低恢复和过滤搜索的主机开销，并避免加载未请求的向量字段。
• 飞书/Lark URL 可经 UnderstandingAPI 导入：支持异步导入、最终资源 URI 回填、产物图片重写和安全的临时凭证传递。
• Python SDK 支持 HTTP 事件钩子：AsyncHTTPClient 和 SyncHTTPClient 可通过 event_hooks 接入 httpx.AsyncClient 的异步 request/response hooks。

新功能用法

使用多个检索标签

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
)
client.initialize()

results = client.find(
    "rollback runbook",
    tags=["env=prod", "team=search"],
)

上述查询只返回同时包含 env=prod 和 team=search 的结果。标签必须使用严格的 k=v 格式。

为 Python SDK 添加请求钩子

from openviking_sdk import AsyncHTTPClient


async def on_request(request):
    print(request.method, request.url)


client = AsyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-key",
    event_hooks={"request": [on_request]},
)
await client.initialize()

启用 cuVS micro-batching

{
  "storage": {
    "vectordb": {
      "backend": "cuvs",
      "cuvs": {
        "algorithm": "brute_force",
        "max_concurrent_gpu_searches": 1,
        "micro_batching_enabled": true,
        "micro_batching_max_batch_size": 8,
        "micro_batching_max_wait_ms": 1.0
      }
    }
  }
}

该能力默认关闭，当前仅支持 brute_force，并要求 max_concurrent_gpu_searches 为 1。批大小范围为 1-8，等待时间范围为 0-100 ms。

使用用户 token 导入飞书/Lark 文档

client.add_resource(
    "https://example.feishu.cn/docx/doc_token",
    args={"feishu_access_token": "u-..."},
)

一次性导入不会保存 user access token。若配置 watch_interval > 0，还需要传入 feishu_refresh_token，并在服务端配置签发这些 token 的同一个飞书应用。

体验与兼容性改进

• 多标签查询从宽松匹配调整为全部匹配；升级前请检查依赖“任一标签命中”的调用。
• TypeScript SDK 现在区分调用方取消和超时，分别返回 ABORTED 和 DEADLINE_EXCEEDED。
• 对上传后的一次性快照设置 watch_interval > 0 现在会直接报错，避免反复处理冻结内容；需要更新时应重新上传。
• 默认事务锁失效时间从 300 秒延长到 1800 秒，减少长任务被误判为陈旧锁的风险。
• Python SDK 文档示例补齐显式 initialize() 调用。
• CLI 保留服务端结构化错误信息，便于脚本和用户区分具体失败原因。

修复

• 解析与导入：正确应用 Markdown frontmatter 配置；支持带括号的 Markdown 图片路径；规范化带参数的 MIME 类型；允许导入无扩展名的 README 文件；修复飞书资源名称前缀。
• 资源与任务：隔离外部解析队列；恢复重启后的 add-resource 任务；隔离未解析 URI 操作；改进异步资源导入的锁交接和最终 URI 处理。
• 会话与记忆：get_session_context() 重新包含归档中的进行中消息；redo 恢复后重新触发向量化；嵌套记忆写入正确传递事务锁。
• 存储与检索：修复双路径和精确路径锁；提升 cuVS 恢复、过滤路由和并发搜索稳定性；减少不必要的向量物化。
• 模型与集成：兼容 DashScope rerank 的嵌套请求/响应封装；修复 OpenCode/Codex recall 恢复、Windows spawn 失败和 OpenClaw/OpenCode 插件契约问题。
• Bot 与网关：所有频道适配器统一传递 sender_name，并恢复由配置启动的网关日志。

文档、测试与安全

• ov config show 现在会遮蔽 gateway token 和额外请求头中的敏感值；Unix 上新建的 root key 文件使用 0600 权限。
• 更新项目 README 和 ov CLI 文档，并新增 OpenViking Helper 集成、OpenClaw 手动配置、Python 安装器标签页、Hermes 隔离安装和 S3 兼容存储注意事项。
• 扩充 cuVS、资源导入、解析器、检索标签、会话、事务锁、SDK 和安全相关回归测试。

---

English

Overview

OpenViking v0.4.11 is a 45-commit maintenance and performance release. It focuses on retrieval-tag semantics, cuVS query throughput, Feishu/Lark resource ingestion, and Python SDK observability, while fixing reliability issues across resource queues, transaction locks, session context, parsers, and the CLI.

Highlights

• Strict AND semantics for retrieval tags: multiple tags passed to find() or search() now require every tag to be present. REST, Python SDK, CLI, local-client, and LangChain behavior is aligned.
• Optional cuVS request micro-batching: compatible exact brute-force queries can share one GPU matrix-search call. Recovery and filtered-search host overhead are also reduced, and unrequested vector fields are no longer hydrated.
• Feishu/Lark URLs through UnderstandingAPI: the ingestion path now supports asynchronous imports, final resource-URI persistence, artifact image rewriting, and safer temporary credential handling.
• Python SDK HTTP event hooks: AsyncHTTPClient and SyncHTTPClient accept event_hooks compatible with asynchronous httpx.AsyncClient request and response hooks.

New Feature Usage

Search with multiple retrieval tags

import openviking as ov

client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
)
client.initialize()

results = client.find(
    "rollback runbook",
    tags=["env=prod", "team=search"],
)

This query returns only results containing both env=prod and team=search. Tags must use strict k=v syntax.

Add a Python SDK request hook

from openviking_sdk import AsyncHTTPClient


async def on_request(request):
    print(request.method, request.url)


client = AsyncHTTPClient(
    url="http://127.0.0.1:1933",
    api_key="your-key",
    event_hooks={"request": [on_request]},
)
await client.initialize()

Enable cuVS micro-batching

{
  "storage": {
    "vectordb": {
      "backend": "cuvs",
      "cuvs": {
        "algorithm": "brute_force",
        "max_concurrent_gpu_searches": 1,
        "micro_batching_enabled": true,
        "micro_batching_max_batch_size": 8,
        "micro_batching_max_wait_ms": 1.0
      }
    }
  }
}

Micro-batching is disabled by default. It currently supports only brute_force with max_concurrent_gpu_searches set to 1. Batch size accepts 1-8 and wait time accepts 0-100 ms.

Import a Feishu/Lark document with a user token

client.add_resource(
    "https://example.feishu.cn/docx/doc_token",
    args={"feishu_access_token": "u-..."},
)

One-time imports do not retain the user access token. A watch with watch_interval > 0 also requires feishu_refresh_token and matching Feishu app credentials on the server.

Improvements and Compatibility

• Multi-tag retrieval changed from loose matching to all-tags matching; review callers that depended on any-tag behavior.
• The TypeScript SDK now distinguishes caller cancellation from timeout with ABORTED and DEADLINE_EXCEEDED.
• Setting watch_interval > 0 on an uploaded one-time snapshot now fails fast instead of repeatedly processing frozen content; re-upload the source when it changes.
• The default transaction-lock expiry increased from 300 to 1800 seconds to reduce false stale-lock recovery during long operations.
• Python SDK examples now show the explicit initialize() call.
• The CLI preserves structured server errors so scripts and users can identify specific failures.

Fixes

• Parsing and ingestion: honor Markdown frontmatter configuration; handle parentheses in Markdown image paths; normalize parameterized MIME types; import extensionless README files; preserve Feishu resource-name prefixes.
• Resources and tasks: isolate external parsing work; recover add-resource jobs after restart; isolate unresolved URI operations; improve lock handoff and final-URI handling for asynchronous imports.
• Sessions and memory: include in-flight archived messages in get_session_context(); restore vectorization after redo recovery; propagate transaction locks through nested memory writes.
• Storage and retrieval: fix dual-path and exact-path locking; improve cuVS recovery, filter routing, and concurrent-search stability; avoid unnecessary vector materialization.
• Models and integrations: support DashScope's nested rerank envelope; restore OpenCode/Codex recall behavior; handle Windows spawn failures; align OpenClaw and OpenCode plugin contracts.
• Bots and gateway: pass sender_name through every channel adapter and restore logs for gateways started from configuration.

Docs, Tests, and Security

• ov config show now redacts gateway tokens and extra-header values. Newly created root-key files use mode 0600 on Unix.
• Project and ov CLI documentation was refreshed, with new OpenViking Helper integration, OpenClaw manual setup, Python installer tabs, isolated Hermes installation, and S3-compatible storage guidance.
• Regression coverage was expanded for cuVS, resource ingestion, parsing, retrieval tags, sessions, transaction locks, SDK behavior, and security-sensitive configuration.