Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

## Unreleased

- 探索页新增「对比」:同一问题在 2–3 种检索模式下并排检索,显示耗时、召回数、SAG2 的 JEV 用量与共同命中的片段,可选 LLM 评审,并可一键按某一模式正式检索。
- SAG2 只读引擎改在专用事件循环线程运行:大范围检索构建内存语料时不再阻塞 API 事件循环;整次超时会同步取消引擎侧工作。
- 问答页可为当前轮次选择检索模式:输入框工具栏新增与探索页一致的模式控件,默认显示将实际使用的模式及其来源(人格默认 / 信源默认 / 全局),用户选择后对后续轮次生效;付费 JEV 模式缺少 API Key 时在开始生成前拒绝并给出设置入口。回答的活动时间线显示本轮实际模式与来源。
- 信源可设置「默认检索模式」:创建或编辑信源时选择快速、精确、JEV 精排或 SAG2 证据检索,并以通俗说明与付费提示帮助选择;JEV 模式缺少 API Key 时可在对话框内直接配置。搜索与问答在所选范围内信源一致时自动采用该默认(显式选择与 Agent 人格优先),结果 `stats.strategy_origin` 标明来源。不改变文档入库流程。
- 新增可选 SAG2 证据检索模式(`sag2`):接入 `zleap-sag2` 0.1.0,只读直搜 SQLite / PostgreSQL 关系库,BM25 召回后由 JEV 服务多轮评分,不依赖向量库,文档入库后即可检索;与 JEV 精排共用服务配置,失败不回退,首期不支持 MySQL / OceanBase。
Expand Down
2 changes: 1 addition & 1 deletion README-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -570,7 +570,7 @@ config = EngineConfig.from_env()

这里列出的是应用/API 策略名称;应用将 `multi` 映射到 Python 引擎的 `full_expand`,将 `multi_es_fast` 映射到 `pruned_expand_rff`,`sag2` 由独立的 `zleap-sag2` 引擎执行。可用性取决于存储能力:`multi_es_fast` 与 `multi_jev` 需要词法检索支持,`sag2` 需要 SQLite 或 PostgreSQL 关系库。

每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。
每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换;探索页还可开启「对比」,用同一问题并排比较 2–3 种模式的耗时、召回与用量,并一键采用其中一种。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。

在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**;创建信源时选择 JEV 模式也可在对话框内直接完成该配置。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -568,7 +568,7 @@ Pipeline request and result types are available from `zleap.sag.pipeline`: `Pars

These are the application/API strategy names; the application maps `multi` to the Python engine's `full_expand` and `multi_es_fast` to `pruned_expand_rff`, while `sag2` runs on the separate `zleap-sag2` engine. Availability depends on storage capabilities: `multi_es_fast` and `multi_jev` require lexical search support; `sag2` requires a SQLite or PostgreSQL relational store.

Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Both the explore page and the chat composer offer a mode control for a one-off switch on the current query or turn. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion.
Each source can carry a **default retrieval mode**, chosen when the source is created or edited; unset means follow the global default. Both the explore page and the chat composer offer a mode control for a one-off switch on the current query or turn; the explore page can also run a side-by-side comparison of two or three modes for the same question (latency, hits, usage) and adopt one with a click. Search and chat resolve the mode as explicit request → agent persona → the shared default of every source in scope → global default, falling back to the global default when sources in scope disagree; `stats.strategy_origin` reports which one applied. The setting only affects retrieval and never changes document ingestion.

Configure 302.AI, TypeSafe, or a custom JEV service in **Settings → Knowledge → Retrieval** (default model: `jev-latest`, separate API key), then select **JEV reranking** or **SAG2 evidence retrieval**; choosing a JEV mode while creating a source offers the same configuration inline. JEV is a paid service: saving the service alone does not enable it, and an API key is required before either JEV mode can be selected. JEV reranking has a 30-second default deadline; failures return an error unless coarse fallback is enabled.

Expand Down
143 changes: 107 additions & 36 deletions apps/api/sag_api/sag/sag2_engine.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,18 @@

对 zleap-sag2 内部结构的依赖集中在 ``_sag_schema_present`` 与 ``_count_scope`` 两个
函数里(``engine.store.engine`` 是其关系库连接);升级 ``zleap-sag2`` 版本时需复核这两处。

zleap-sag2 0.1.0 在构建内存语料时会在事件循环线程上同步分词、建倒排表,范围越大阻塞越久。
为此只读引擎及其全部协程都运行在一个专用线程的事件循环里(``_EngineLoop``),
API 事件循环只负责排队、超时与取消,不被扫描阻塞。
"""

from __future__ import annotations

import asyncio
import threading
import time
from collections.abc import Callable
from collections.abc import Callable, Coroutine
from pathlib import Path
from typing import TYPE_CHECKING, Any

Expand Down Expand Up @@ -226,9 +231,48 @@ async def drain(self) -> None:
await self._condition.wait_for(lambda: self._active == 0)


class _EngineLoop:
"""专用线程上的事件循环:承载只读引擎的连接、扫描与评分,不占用 API 循环。

``run`` 从 API 循环提交协程并等待结果;等待方被取消(如整次超时)时同步取消
专用循环里的协程,避免遗留仍在扫描的工作。
"""

def __init__(self, name: str = "sag2-engine") -> None:
self._loop = asyncio.new_event_loop()
self._thread = threading.Thread(target=self._serve, name=name, daemon=True)
self._thread.start()

def _serve(self) -> None:
asyncio.set_event_loop(self._loop)
try:
self._loop.run_forever()
finally:
self._loop.close()

@property
def alive(self) -> bool:
return self._thread.is_alive()

async def run(self, coroutine: Coroutine[Any, Any, Any]) -> Any:
future = asyncio.run_coroutine_threadsafe(coroutine, self._loop)
try:
return await asyncio.wrap_future(future)
except asyncio.CancelledError:
future.cancel()
raise

def stop(self, timeout: float = 5.0) -> None:
if not self._thread.is_alive():
return
self._loop.call_soon_threadsafe(self._loop.stop)
self._thread.join(timeout=timeout)


class Sag2EngineHolder:
"""按配置指纹懒建、复用、重建一个只读 zleap-sag2 引擎,并限制并发检索数。

引擎只在专用线程的事件循环里创建和使用;``_gate`` 与整次超时留在 API 循环。
``scorer_factory`` 仅供测试注入离线评分器;缺省由引擎按 ``JevConfig`` 创建真实客户端。
"""

Expand All @@ -239,6 +283,12 @@ def __init__(self, settings: Settings, *, scorer_factory: Callable[[Any], Any] |
self._fingerprint: tuple[Any, ...] | None = None
self._lock = asyncio.Lock()
self._gate = _AdmissionGate(settings.sag2_max_concurrent_searches)
self._loop: _EngineLoop | None = None

def _engine_loop(self) -> _EngineLoop:
if self._loop is None or not self._loop.alive:
self._loop = _EngineLoop()
return self._loop

@property
def started(self) -> bool:
Expand All @@ -258,8 +308,18 @@ async def refresh(self, settings: Settings) -> None:
await self._gate.set_limit(settings.sag2_max_concurrent_searches)

async def aclose(self) -> None:
"""等待在途检索结束后关闭引擎;与 ``EngineManager._close_all_slots`` 等待空闲的语义一致。"""
"""等待在途检索结束后关闭引擎并停掉专用循环;与 ``_close_all_slots`` 等待空闲的语义一致。"""
await self._gate.drain()
loop, self._loop = self._loop, None
if loop is not None and loop.alive:
try:
await loop.run(self._locked_close())
finally:
await asyncio.to_thread(loop.stop)
else:
await self._locked_close()

async def _locked_close(self) -> None:
async with self._lock:
await self._close()

Expand Down Expand Up @@ -352,43 +412,54 @@ async def _run(
source_ids: tuple[str, ...] | None,
top_k: int,
) -> tuple[Any, int]:
async with self._gate:
# 排队在 API 循环完成;引擎工作整体交给专用循环,扫描不阻塞其他请求。
return await self._engine_loop().run(self._execute(query, data_source_ids, source_ids, top_k))

async def _execute(
self,
query: str,
data_source_ids: list[str],
source_ids: tuple[str, ...] | None,
top_k: int,
) -> tuple[Any, int]:
"""在专用循环里运行:取引擎、范围护栏、构造请求、检索与异常翻译。"""
from zleap.sag2 import SearchOptions, SearchRequest, SearchScope

async with self._gate:
engine = await self.engine()
settings = self._settings
scope_chunks = await self._count_scope(engine, data_source_ids)
limit = int(settings.sag2_max_scope_chunks)
if limit and scope_chunks > limit:
raise ValidationError(
f"检索范围过大:包含 {scope_chunks:,} 个段落,超过 SAG2 证据检索上限 {limit:,},请缩小信源范围",
layer=ErrorLayer.ENGINE,
stage=ErrorStage.RETRIEVE,
)
scope_values: dict[str, Any] = {"data_source_ids": tuple(data_source_ids)}
if source_ids is not None:
scope_values["source_ids"] = source_ids
request = SearchRequest(
query=query,
scope=SearchScope(**scope_values),
options=SearchOptions(
candidate_k=settings.sag2_candidate_k,
seed_k=settings.sag2_seed_k,
max_hops=settings.sag2_max_hops,
expansion_term_limit=settings.sag2_expansion_term_limit,
top_k=max(1, min(int(top_k), 1000)),
),
)
started = time.perf_counter()
try:
result = await engine.search(request)
except Exception as error: # noqa: BLE001 - translated below
raise self._translate(error) from error
log.info(
"SAG2 检索完成 sources=%d scope_chunks=%d hits=%d elapsed=%.0fms",
len(data_source_ids), scope_chunks, len(result.chunks), (time.perf_counter() - started) * 1000,
engine = await self.engine()
settings = self._settings
scope_chunks = await self._count_scope(engine, data_source_ids)
limit = int(settings.sag2_max_scope_chunks)
if limit and scope_chunks > limit:
raise ValidationError(
f"检索范围过大:包含 {scope_chunks:,} 个段落,超过 SAG2 证据检索上限 {limit:,},请缩小信源范围",
layer=ErrorLayer.ENGINE,
stage=ErrorStage.RETRIEVE,
)
return result, scope_chunks
scope_values: dict[str, Any] = {"data_source_ids": tuple(data_source_ids)}
if source_ids is not None:
scope_values["source_ids"] = source_ids
request = SearchRequest(
query=query,
scope=SearchScope(**scope_values),
options=SearchOptions(
candidate_k=settings.sag2_candidate_k,
seed_k=settings.sag2_seed_k,
max_hops=settings.sag2_max_hops,
expansion_term_limit=settings.sag2_expansion_term_limit,
top_k=max(1, min(int(top_k), 1000)),
),
)
started = time.perf_counter()
try:
result = await engine.search(request)
except Exception as error: # noqa: BLE001 - translated below
raise self._translate(error) from error
log.info(
"SAG2 检索完成 sources=%d scope_chunks=%d hits=%d elapsed=%.0fms",
len(data_source_ids), scope_chunks, len(result.chunks), (time.perf_counter() - started) * 1000,
)
return result, scope_chunks

@staticmethod
async def _sag_schema_present(engine: Any) -> bool:
Expand Down
71 changes: 66 additions & 5 deletions apps/api/tests/test_sag2_retrieval.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
"""Offline contracts for the SAG2 evidence strategy (zleap-sag2 read-only search)."""

import asyncio
import threading
import time

import pytest

Expand Down Expand Up @@ -308,7 +310,8 @@ async def test_refresh_applies_new_concurrency_limit_without_dropping_inflight_s

configuration = sag2_settings(sag2_max_concurrent_searches=1)
holder = Sag2EngineHolder(configuration)
release, first_running = asyncio.Event(), asyncio.Event()
# The engine runs on the holder's dedicated loop thread, so signal across threads.
release, first_running = threading.Event(), threading.Event()
active = peak = 0

class Engine:
Expand All @@ -317,7 +320,7 @@ async def search(self, request):
active += 1
peak = max(peak, active)
first_running.set()
await release.wait()
await asyncio.to_thread(release.wait, 5)
active -= 1
return SearchResult(query=request.query, original_query=request.query)

Expand All @@ -336,15 +339,73 @@ def run():
))

first, second = run(), run()
await asyncio.wait_for(first_running.wait(), timeout=1)
await asyncio.sleep(0.01)
assert await asyncio.to_thread(first_running.wait, 1)
await asyncio.sleep(0.05)
assert active == 1 # the second search queues behind the limit of 1
await holder.refresh(configuration.model_copy(update={"sag2_max_concurrent_searches": 2}))
await asyncio.sleep(0.01)
await asyncio.sleep(0.05)
assert active == 2 # the raised limit admits the queued search; the first keeps running
release.set()
await asyncio.gather(first, second)
assert peak == 2
await holder.aclose()


@pytest.mark.asyncio
async def test_engine_work_runs_off_the_api_loop_and_timeouts_cancel_it(monkeypatch):
from zleap.sag2 import SearchResult

holder = Sag2EngineHolder(sag2_settings())
cancelled = threading.Event()

class Engine:
async def search(self, request):
if request.query == "block":
time.sleep(0.3) # synchronous corpus build: must not stall the API loop
return SearchResult(query=request.query, original_query=request.query)
try:
await asyncio.sleep(5)
except asyncio.CancelledError:
cancelled.set()
raise
return SearchResult(query=request.query, original_query=request.query)

async def engine():
return Engine()

async def count(_engine, _data_source_ids):
return 1

monkeypatch.setattr(holder, "engine", engine)
monkeypatch.setattr(holder, "_count_scope", count)

def run(query):
return holder.search(
[("cfg-1", None)], query, top_k=3, requested_sources=1, source_limit_applied=False,
source_ids_by_config=None,
)

# While the engine blocks its own thread, the API loop keeps ticking.
ticks = 0

async def ticker():
nonlocal ticks
for _ in range(10):
await asyncio.sleep(0.02)
ticks += 1

await asyncio.gather(run("block"), ticker())
assert ticks == 10
assert threading.current_thread() is threading.main_thread()

# The whole-search timeout cancels the coroutine inside the dedicated loop.
holder._settings.sag2_search_timeout_seconds = 1.0
with pytest.raises(ServiceUnavailableError):
await run("hang")
assert cancelled.wait(1)
assert holder._gate.active == 0
await holder.aclose()
assert holder._loop is None


@pytest.mark.parametrize(("status", "expected_type", "expected_message"), [
Expand Down
Loading
Loading