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

- 问答页可为当前轮次选择检索模式:输入框工具栏新增与探索页一致的模式控件,默认显示将实际使用的模式及其来源(人格默认 / 信源默认 / 全局),用户选择后对后续轮次生效;付费 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。
- JEV 为付费服务:选择 JEV 精排或 SAG2 证据检索前必须填写 API Key;仅保存服务地址不再足以启用模式,连接测试也要求 Key。探索页灰置项直接给出原因与设置入口,SAG2 结果显示本次评分用量。
- 后端中文分词依赖由 `jieba-py` 改回 `jieba` 0.42.1,与 `zleap-sag2` 共用一份词典;分词结果不变。
Expand Down
4 changes: 3 additions & 1 deletion README-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -570,7 +570,9 @@ 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 关系库。

在“设置 → 知识库 → 检索”配置 302.AI、TypeSafe 官方或自定义 JEV 服务(默认 `jev-latest`,独立 API Key),再选择 **JEV 精排** 或 **SAG2 证据检索**。JEV 是付费服务:仅保存服务不会启用,选择任一 JEV 模式前必须填写 API Key。JEV 精排默认限时 30 秒、失败报错,可选择粗排降级。
每个信源可在创建或编辑时设置**默认检索模式**;未设置则跟随全局默认。探索页与问答页的输入框都提供模式控件,可为当前查询或当前轮次临时切换。搜索与问答按“本次显式选择 → Agent 人格 → 范围内信源的共同默认 → 全局默认”解析模式,范围内信源默认不一致时按全局默认处理;结果 `stats.strategy_origin` 标明来源。该设置只影响检索,不改变文档入库流程。

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

**SAG2 证据检索**与 JEV 精排共用同一服务配置,但不经向量库:它直接只读 SAG 的 SQLite / PostgreSQL 关系库(首期不支持 MySQL / OceanBase),文档分块入库后即可检索,不要求事件抽取完成,pgvector 单库部署也可使用。每次检索会扫描所选信源的全部段落并多轮调用 JEV,用量高于 JEV 精排;失败直接报错,不支持粗排降级。候选数、超时、并发与范围上限等调优参数见 `apps/api/.env.example` 的 `SAG_SAG2_*`。使用 PostgreSQL 时,连接用户需能在目标 schema 创建并读写 `sag2_state`、`sag2_search_sessions` 两张辅助表,并对 `sag2_state` 执行 `LOCK TABLE`;SAG 的业务表保持只读。

Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -568,7 +568,9 @@ 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.

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**. 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.
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.

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.

**SAG2 evidence retrieval** shares the JEV service configuration but bypasses the vector store: it reads SAG's SQLite or PostgreSQL relational store directly (MySQL and OceanBase are not supported yet), documents become searchable as soon as they are chunked and stored, event extraction is not required, and pgvector single-database deployments can use it. Each search scans every passage of the selected sources and calls JEV over several rounds, so it costs more than JEV reranking; failures are reported as errors, with no coarse fallback. Tuning knobs for candidates, timeouts, concurrency and scope limits are documented as `SAG_SAG2_*` in `apps/api/.env.example`. On PostgreSQL the connecting role must be able to create and use the two auxiliary tables `sag2_state` and `sag2_search_sessions` in the target schema and to `LOCK TABLE` `sag2_state`; SAG's own tables stay read-only.

Expand Down
5 changes: 5 additions & 0 deletions apps/api/sag_api/api/v1/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
from sse_starlette.sse import EventSourceResponse

from sag_agent import AgentRuntime, EventType, RunHandle
from sag_api.core.config import settings
from sag_api.core.db import SessionLocal, get_session
from sag_api.core.deps import (
get_agent_runtime,
Expand Down Expand Up @@ -351,6 +352,9 @@ async def ask(
thread = await svc.get_thread(session, agent.id, thread_id)
if not llm.configured:
raise ConfigurationError("尚未配置 LLM,无法生成回答")
if body.strategy is not None:
# 本轮显式选择的模式必须可用(付费 JEV 模式需已配置 Key);在流开始前就拒绝。
EngineManager.require_strategy_available(settings, body.strategy)
plan = await svc.prepare_ask(
session,
agent=agent,
Expand All @@ -359,6 +363,7 @@ async def ask(
attachments=body.attachments,
source_ids=body.source_ids,
llm=llm,
strategy=body.strategy,
)
web_enabled = body.effective_web_enabled

Expand Down
7 changes: 5 additions & 2 deletions apps/api/sag_api/api/v1/search.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
event_scores_from_evidence,
published_document_inputs,
recall_event_scores,
resolve_search_strategy,
retrieve_relevant_sections,
stream_synthesize_search_answer,
synthesize_search_answer,
Expand Down Expand Up @@ -170,12 +171,14 @@ async def _retrieve_search_evidence(
body: SearchRequest | GlobalSearchRequest,
) -> tuple[SearchOutcome, EventScoreMap, bool]:
configuration = getattr(engine_manager, "_settings", settings)
strategy = body.strategy or configuration.search_strategy
# Resolve once for the evidence-shape decision below; the retrieval service
# resolves the same inputs again and records where the mode came from.
strategy = resolve_search_strategy(requested=body.strategy, sources=sources, configuration=configuration).strategy
retrieval = retrieve_relevant_sections(
engine_manager,
sources,
body.query,
strategy=strategy,
strategy=body.strategy,
top_k=body.top_k,
include_ranked_candidates=body.include_ranked_candidates,
)
Expand Down
1 change: 1 addition & 0 deletions apps/api/sag_api/core/db.py
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ async def get_session() -> AsyncIterator[AsyncSession]:
# create_all 只建新表、不改旧表,故对演进列做幂等 ADD COLUMN。
_COLUMN_UPGRADES: dict[str, dict[str, str]] = {
"agents": {"is_default": "BOOLEAN NOT NULL DEFAULT FALSE"},
"sources": {"default_search_strategy": "VARCHAR(32)"},
"documents": {
"progress": "INTEGER NOT NULL DEFAULT 0",
"processing_stage": "VARCHAR(32)",
Expand Down
3 changes: 3 additions & 0 deletions apps/api/sag_api/db/models/source.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ class Source(IDMixin, TimestampMixin, Base):
document_count: Mapped[int] = mapped_column(Integer, default=0)
chunk_count: Mapped[int] = mapped_column(Integer, default=0)
event_count: Mapped[int] = mapped_column(Integer, default=0)
# 该信源的默认检索模式;None 表示跟随全局默认。搜索与问答在范围内信源一致时采用,
# 不改变文档入库流程。
default_search_strategy: Mapped[str | None] = mapped_column(String(32), nullable=True)

@hybrid_property
def is_deleting(self) -> bool:
Expand Down
9 changes: 7 additions & 2 deletions apps/api/sag_api/sag/engine_manager.py
Original file line number Diff line number Diff line change
Expand Up @@ -425,12 +425,17 @@ def strategies_capability_report(cls, settings: Settings) -> dict[str, Any]:
return {"enabled": enabled, "disabled": disabled}

@classmethod
def require_jev_capabilities(cls, settings: Settings, strategy: str = "multi_jev") -> None:
"""Reject explicit JEV-scored mode activation before publishing incompatible settings."""
def require_strategy_available(cls, settings: Settings, strategy: str) -> None:
"""Reject selecting a mode the current deployment cannot serve, with its capability reason."""
unavailable = cls.strategies_capability_report(settings)["disabled"].get(strategy)
if unavailable is not None:
raise ConfigurationError(unavailable["message"], code=unavailable["reason"])

@classmethod
def require_jev_capabilities(cls, settings: Settings, strategy: str = "multi_jev") -> None:
"""Reject explicit JEV-scored mode activation before publishing incompatible settings."""
cls.require_strategy_available(settings, strategy)

def _config_for(self, source: Source | None) -> Any:
overrides = None
if source is not None and source.config:
Expand Down
4 changes: 3 additions & 1 deletion apps/api/sag_api/schemas/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

from pydantic import BaseModel, ConfigDict, Field, model_validator

from sag_api.enums import BindingTargetType, MessageRole, MessageStatus
from sag_api.enums import BindingTargetType, MessageRole, MessageStatus, SearchStrategy


class AgentCreate(BaseModel):
Expand Down Expand Up @@ -99,6 +99,8 @@ class MessagePageOut(BaseModel):

class AskRequest(BaseModel):
query: str = Field(default="", max_length=4000)
# 本轮检索模式;未传时按 Agent 人格 → 范围内信源共同默认 → 全局默认解析。
strategy: SearchStrategy | None = None
# 图片附件 id 列表(≤4,经 POST /attachments 上传)
attachments: list[str] = Field(default_factory=list, max_length=4)
# @知识库 范围限定:仅在这些信源内检索(空=默认全部)
Expand Down
7 changes: 6 additions & 1 deletion apps/api/sag_api/schemas/source.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

from pydantic import BaseModel, ConfigDict, Field

from sag_api.enums import ConnectorKind, SourceStatus, SourceType
from sag_api.enums import ConnectorKind, SearchStrategy, SourceStatus, SourceType
from sag_api.schemas.job import JobOut


Expand All @@ -22,12 +22,16 @@ class SourceCreate(BaseModel):
description: str = ""
connector_kind: ConnectorKind = ConnectorKind.FILE_UPLOAD
config: dict[str, Any] = Field(default_factory=dict)
# 默认检索模式;None 表示跟随全局默认。
default_search_strategy: SearchStrategy | None = None


class SourceUpdate(BaseModel):
name: str | None = Field(default=None, max_length=200)
description: str | None = None
status: SourceStatus | None = None
# 显式传 null 表示改回跟随全局默认;未出现则保持不变。
default_search_strategy: SearchStrategy | None = None


class SourceOut(BaseModel):
Expand All @@ -42,6 +46,7 @@ class SourceOut(BaseModel):
document_count: int
chunk_count: int
event_count: int
default_search_strategy: SearchStrategy | None = None
created_at: datetime
updated_at: datetime
deletion_job: JobOut | None = None
3 changes: 3 additions & 0 deletions apps/api/sag_api/services/agent_domain.py
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,7 @@ class AskPlan:
source_ids: list[str] | None = None # @范围:限定循环内检索工具可见的信源
source_scope: list[dict[str, str]] | None = None
user_message_id: str | None = None
strategy: str | None = None # 本轮显式选择的检索模式


def build_ask_context(
Expand Down Expand Up @@ -510,6 +511,7 @@ async def prepare_ask(
attachments: list[str] | None = None,
source_ids: list[str] | None = None,
llm=None,
strategy: str | None = None,
) -> AskPlan:
"""落库用户消息(含图片附件 meta)、解析历史(超上下文阈值时主动压缩),组装计划。"""
resolved: list[dict] = []
Expand Down Expand Up @@ -554,6 +556,7 @@ async def prepare_ask(
)
plan.user_message_id = user_msg.id
plan.source_scope = source_scope
plan.strategy = strategy
return plan


Expand Down
1 change: 1 addition & 0 deletions apps/api/sag_api/services/agent_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ async def generate_stream(
sources=sources,
persona=agent.persona or {},
agent=agent,
requested_strategy=plan.strategy,
)

try:
Expand Down
7 changes: 5 additions & 2 deletions apps/api/sag_api/services/agent_tooling.py
Original file line number Diff line number Diff line change
Expand Up @@ -348,8 +348,11 @@ def _adapt_tool(host_tool, host_context: HostToolContext, citations: list[dict])
from sag_api.tools.builtin import knowledge_search_strategy

configuration = getattr(host_context.engine_manager, "_settings", settings)
strategy = knowledge_search_strategy(host_context.persona, configuration)
# Keep this run's mode stable while the model prepares the tool call.
strategy = knowledge_search_strategy(
host_context.persona, configuration, host_context.sources, host_context.requested_strategy,
)
# Keep this run's mode stable while the model prepares the tool call; the
# explicit turn choice stays in requested_strategy so its origin is reported.
host_context = replace(host_context, persona={**host_context.persona, "search_strategy": strategy})
if strategy == "multi_jev":
source_count = min(len(host_context.sources), configuration.search_source_candidate_limit)
Expand Down
46 changes: 45 additions & 1 deletion apps/api/sag_api/services/retrieval_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,47 @@ class SearchSource(Protocol):

EventScoreMap = dict[tuple[str, str], float]
DocumentSourceScope = dict[str, tuple[str, ...]]
StrategyOrigin = Literal["request", "persona", "source_default", "global"]


@dataclass(frozen=True, slots=True)
class ResolvedSearchStrategy:
"""The mode a retrieval will run with and where that choice came from."""

strategy: str
origin: StrategyOrigin


def common_source_default_strategy(sources) -> str | None:
"""范围内每个信源都设置了同一默认模式时返回它;有信源未设置或不一致则返回 None。

混合范围不猜测:一个信源的偏好不应改变其他信源的检索方式。
"""
defaults: set[str] = set()
for source in sources:
value = getattr(source, "default_search_strategy", None)
if not value:
return None
defaults.add(normalize_search_strategy(str(value)))
return next(iter(defaults)) if len(defaults) == 1 else None


def resolve_search_strategy(
*,
requested: str | None = None,
persona_strategy: str | None = None,
sources=(),
configuration: Any = settings,
) -> ResolvedSearchStrategy:
"""显式请求 → Agent 人格 → 范围内信源的共同默认 → 全局默认。"""
if requested:
return ResolvedSearchStrategy(requested, "request")
if persona_strategy:
return ResolvedSearchStrategy(persona_strategy, "persona")
common = common_source_default_strategy(sources)
if common:
return ResolvedSearchStrategy(common, "source_default")
return ResolvedSearchStrategy(configuration.search_strategy, "global")


def event_scores_from_evidence(sections: list[RetrievedSection]) -> EventScoreMap:
Expand Down Expand Up @@ -324,7 +365,8 @@ async def retrieve_relevant_sections(

total_start = time.perf_counter()
configuration = getattr(engine_manager, "_settings", settings)
requested_strategy = strategy or configuration.search_strategy
resolved = resolve_search_strategy(requested=strategy, sources=sources, configuration=configuration)
requested_strategy = resolved.strategy
mode = normalize_search_strategy(requested_strategy)
if mode in JEV_SCORED_STRATEGIES:
# The JEV-scored profile owns recall and final scoring. Adding application
Expand All @@ -351,6 +393,7 @@ async def retrieve_relevant_sections(
return SearchOutcome(query=outcome.query or query, sections=visible_sections[:requested_limit], stats={
**outcome.stats,
"requested_strategy": requested_strategy,
"strategy_origin": resolved.origin,
"requested_top_k": requested_limit,
"candidate_top_k": requested_limit,
"candidates": len(outcome.sections),
Expand Down Expand Up @@ -416,6 +459,7 @@ def visible(section: RetrievedSection) -> bool:
stats = {
**outcome.stats,
"requested_strategy": requested_strategy,
"strategy_origin": resolved.origin,
"requested_top_k": requested_limit,
"candidate_top_k": candidate_limit,
"candidates": reranked.candidate_count,
Expand Down
Loading
Loading