数据库与存储 API 参考

本页是“代码级参考”，通过 mkdocstrings 从源码生成。若你想先了解全局设计，请先看：

• docs/core/storage.md
• docs/database/schema.md
• docs/database/migrations.md

文档定位

本页解决的是“代码里有哪些数据库 / 存储对象和公开函数可以直接用”。

它不重复解释：

• 为什么存储要分 PostgreSQL / Qdrant / MinIO 三层
• 表关系和索引应该如何理解
• 迁移 revision 应该怎么管理

这些问题分别由：

• 存储架构
• 数据模式与关系
• 迁移与版本管理

来解释。

总览

数据层 API 分为四类：

• 数据库引擎与会话
• ORM 模型与数据访问函数
• MinIO 文件存储服务
• Qdrant 向量检索服务

数据库引擎与会话

ai_service.utils.database

通用数据库连接模块。

此模块提供 SQLAlchemy 数据库连接和会话管理功能（PostgreSQL）。

create_database_engine

create_database_engine(**kwargs)

创建数据库引擎。

参数：

名称	类型	描述	默认
**kwargs	Any	传递给 create_engine 的额外参数	{}

返回：

类型	描述
Engine	sqlalchemy.engine.Engine: 数据库引擎实例

引发：

类型	描述
SQLAlchemyError	当引擎创建失败时抛出

示例：

>>> engine = create_database_engine(echo=True)
>>> engine = create_database_engine(pool_size=10)

get_db

get_db()

获取数据库会话（生成器模式）

用于依赖注入场景（如 FastAPI）

产生：

名称	类型	描述
Session	Session	数据库会话实例

引发：

类型	描述
SQLAlchemyError	当创建会话失败时抛出

示例：

>>> from ai_service.utils.database import get_db
>>>
>>> # FastAPI 中使用
>>> @app.get("/items/")
>>> def read_items(db: Session = Depends(get_db)):
>>>     return db.query(Item).all()

init_database

init_database(base=None)

初始化数据库

创建所有表结构

参数：

名称	类型	描述	默认
base	Any | None	SQLAlchemy 声明式基类，默认使用本模块的 Base	None

引发：

类型	描述
SQLAlchemyError	当创建表失败时抛出

示例：

>>> from ai_service.utils.database import init_database
>>> init_database()

ORM 模型与数据访问

兼容性说明：

• 对外稳定导入面仍然是 ai_service.storage.models
• 具体实现已拆分到 ai_service.storage.model_domains/，按 domain 分为 sessions、agents、jobs、knowledge、documents、evaluations、skills、mcp
• 新增的定时任务 domain 位于 scheduled_tasks，用于 future schedule、worker lease 与执行审计持久化
• Alembic、测试和服务层仍然可以继续通过 ai_service.storage.models 触发完整的 ORM metadata 注册
• 知识库挂载删除的规范入口已切换为 get_agent_knowledge_link_by_id() + delete_agent_knowledge_link(mount_id=...)；delete_agent_knowledge_link(agent_id=..., source_id=...) 仅保留为兼容期回退路径
• conversation_turns 现在直接持久化 turn 级 generation token 统计；scheduled_task_runs 继续只保存 conversation_turn_id，控制面需要从 turn 反查 usage
• agent_evaluation_results 会分别保存 generation/judge 的 item 级 usage，agent_evaluation_runs 会保存 run 级 rollup 与来源质量 breakdown

ai_service.storage.models

Compatibility barrel for storage models and data-access helpers.

This module preserves the historical ai_service.storage.models import path while the implementation lives in ai_service.storage.model_domains.

Session

Bases: Base

Represents a conversation session.

属性：

名称	类型	描述
id	str	Unique session identifier.
status	str	Current session status (AI_ACTIVE or HUMAN_ACTIVE).
model_name	Optional[str]	Override model name for this session.
model_provider	Optional[str]	Override model provider for this session.
model_temperature	Optional[float]	Override temperature for this session.
agent_id	Optional[str]	Associated agent for knowledge filtering.
takeover_owner_id_snapshot	Optional[str]	Current active operator id.
takeover_owner_name_snapshot	Optional[str]	Current active operator name.
takeover_started_at	Optional[datetime]	When the latest takeover started.
takeover_released_at	Optional[datetime]	When the latest takeover ended.
created_at	datetime	When the session was created.
updated_at	datetime	When the session was last updated.

Message

Bases: Base

Represents a single chat message.

属性：

名称	类型	描述
id	str	Unique message identifier.
session_id	str	Foreign key to the owning session.
role	str	Message role (user, assistant, agent).
content	str	Message content text.
sender_id_snapshot	Optional[str]	Manual sender/operator identifier.
sender_name_snapshot	Optional[str]	Manual sender/operator display name.
created_at	datetime	When the message was created.

SessionTakeoverEvent

Bases: Base

Represents one durable audit event for human takeover control.

ConversationTurn

Bases: Base

Represents one user-to-assistant response turn for observability.

属性：

名称	类型	描述
id	str	Unique turn identifier.
session_id	str	Owning session identifier.
agent_id	Optional[str]	Agent identifier used for the turn.
user_id	Optional[str]	End-user identifier forwarded from the chat request.
trace_id	Optional[str]	Shared trace id for skill/mcp correlation.
user_message_id	Optional[str]	Message id for user-side input.
assistant_message_id	Optional[str]	Message id for assistant output.
message_type	str	Normalized inbound message type.
model_name	Optional[str]	Effective model name.
model_provider	Optional[str]	Effective model provider.
model_temperature	Optional[float]	Effective model temperature.
input_tokens	Optional[int]	Prompt-side token usage for the turn.
output_tokens	Optional[int]	Response-side token usage for the turn.
total_tokens	Optional[int]	Total token usage for the turn.
token_usage_source	Optional[str]	Token-usage provenance marker.
exclude_from_request_limits	bool	Whether this persisted turn should be excluded from request-count quota calculations.
started_at	Optional[datetime]	Turn start timestamp.
completed_at	Optional[datetime]	Turn completion timestamp.
created_at	datetime	Turn creation timestamp.

TurnContextSnapshot

Bases: Base

Persisted normalized context payload for one conversation turn.

属性：

名称	类型	描述
id	str	Snapshot identifier.
turn_id	str	Owning turn identifier.
system_prompt_preview	Optional[str]	System prompt preview text.
effective_input_preview	Optional[str]	Effective prompt preview text.
prompt_hash	Optional[str]	Prompt hash for stable comparison.
context_payload_json	Optional[str]	Full normalized context payload JSON.
rag_context_json	Optional[str]	RAG provenance payload JSON.
skill_context_json	Optional[str]	Skill context payload JSON.
mcp_context_json	Optional[str]	MCP context payload JSON.
redaction_policy_version	Optional[str]	Redaction policy marker.
created_at	datetime	Snapshot creation timestamp.

Agent

Bases: Base

Represents an AI agent with configurable knowledge bindings.

Agents can have multiple knowledge sources mounted to them for RAG retrieval. Each agent provides a scoped context for conversations.

属性：

名称	类型	描述
id	str	Unique agent identifier.
name	str	Human-readable agent name.
description	Optional[str]	Detailed agent description.
agent_type	str	Agent type identifier (chat, etl).
status	str	Agent status (active/inactive).
system_prompt	Optional[str]	System prompt for the agent.
model_name	Optional[str]	Default model name for the agent.
model_provider	Optional[str]	Default model provider for the agent.
model_temperature	Optional[float]	Default model temperature for the agent.
model_routing_config_json	Optional[str]	JSON config for chat-agent role-based model routing.
human_takeover_enabled	bool	Whether chat human takeover is enabled.
hide_rag_source_filename	bool	Whether chat RAG prompt injection should hide source filenames from the LLM-facing context text.
orchestrator_key	Optional[str]	Chat orchestrator runtime selection key.
judge_prompt	Optional[str]	Agent-level editable Judge prompt used for evaluation runs. Empty means the built-in Judge prompt is used.
message_type_response_config_json	Optional[str]	JSON config for message_type-based fixed responses.
mcp_response_config_json	Optional[str]	JSON config for Agent-level MCP direct-response and quick-match rules.
mcp_runtime_config_json	Optional[str]	JSON config for Agent-level MCP runtime strategy overrides.
response_grounding_config_json	Optional[str]	JSON config for Agent-level final-response grounding policy.
default_chunking_strategy	Optional[str]	Default chunking strategy for ingestion jobs scoped to this agent.
default_chunking_params_json	Optional[str]	JSON config for default chunking parameters.
max_concurrent_requests	Optional[int]	Optional cap on active chat requests in flight for this agent.
max_total_requests	Optional[int]	Optional cap on cumulative persisted chat turns for this agent.
max_requests_per_day	Optional[int]	Optional cap on persisted chat turns created within the current UTC day.
max_total_tokens_daily	Optional[int]	Optional cap on persisted chat token usage accumulated within the current UTC day.
max_total_tokens_monthly	Optional[int]	Optional cap on persisted chat token usage accumulated within the current UTC month.
max_cost_usd_daily	Optional[float]	Optional cap on estimated chat spend accumulated within the current UTC day.
max_cost_usd_monthly	Optional[float]	Optional cap on estimated chat spend accumulated within the current UTC month.
max_tool_calls_total_per_request	Optional[int]	Optional cap on total Skill and MCP executions within one chat request.
max_requests_per_day_per_user	Optional[int]	Optional cap on persisted chat turns per user within the current UTC day.
max_requests_per_month_per_user	Optional[int]	Optional cap on persisted chat turns per user within the current UTC month.
limit_reached_message	Optional[str]	Optional fixed reply text sent to the user when any cost or rate limit is reached.
public_access_mode	str	Public access mode for public runtime routes.
created_at	datetime	When the agent was created.
updated_at	datetime	When the agent was last updated.

AgentVersion

Bases: Base

Immutable snapshot row for agent configuration history.

属性：

名称	类型	描述
id	str	Unique snapshot identifier.
agent_id	str	Owning agent identifier.
version_number	int	Monotonic version number scoped to one agent.
name	str	Agent name snapshot.
description	Optional[str]	Agent description snapshot.
agent_type	str	Agent type snapshot.
status	str	Agent status snapshot.
system_prompt	Optional[str]	Agent system prompt snapshot.
model_name	Optional[str]	Agent model name snapshot.
model_provider	Optional[str]	Agent provider snapshot.
model_temperature	Optional[float]	Agent temperature snapshot.
model_routing_config_json	Optional[str]	JSON config snapshot for chat-agent role-based model routing.
human_takeover_enabled	bool	Human takeover feature flag snapshot.
hide_rag_source_filename	bool	RAG filename-visibility flag snapshot.
orchestrator_key	Optional[str]	Chat orchestrator runtime selection snapshot.
judge_prompt	Optional[str]	Agent-level Judge prompt snapshot.
message_type_response_config_json	Optional[str]	JSON config snapshot for message_type-based fixed responses.
mcp_response_config_json	Optional[str]	JSON config snapshot for Agent-level MCP direct-response and quick-match rules.
mcp_runtime_config_json	Optional[str]	JSON config snapshot for Agent-level MCP runtime strategy overrides.
response_grounding_config_json	Optional[str]	JSON config snapshot for Agent-level final-response grounding policy.
default_chunking_strategy	Optional[str]	Default chunking strategy snapshot.
default_chunking_params_json	Optional[str]	JSON config snapshot for default chunking parameters.
max_concurrent_requests	Optional[int]	Concurrent-request cap snapshot.
max_total_requests	Optional[int]	Total-request cap snapshot.
max_requests_per_day	Optional[int]	Daily persisted-request cap snapshot.
max_total_tokens_daily	Optional[int]	Daily token cap snapshot.
max_total_tokens_monthly	Optional[int]	Monthly token cap snapshot.
max_cost_usd_daily	Optional[float]	Daily cost cap snapshot.
max_cost_usd_monthly	Optional[float]	Monthly cost cap snapshot.
max_tool_calls_total_per_request	Optional[int]	Per-request total tool call cap snapshot.
max_requests_per_day_per_user	Optional[int]	Daily per-user request cap snapshot.
max_requests_per_month_per_user	Optional[int]	Monthly per-user request cap snapshot.
limit_reached_message	Optional[str]	Custom reply text snapshot for limit violations.
public_access_mode	str	Public access mode snapshot.
snapshot_reason	Optional[str]	Optional operator-provided snapshot note.
created_by	Optional[str]	Optional snapshot actor identifier.
created_at	datetime	Snapshot creation timestamp.

KnowledgeSource

Bases: Base

Represents a knowledge source (document collection) for RAG retrieval.

Knowledge sources are collections of documents stored in MinIO and indexed for vector search. They can be mounted to agents for scoped retrieval.

属性：

名称	类型	描述
id	str	Unique knowledge source identifier.
name	str	Human-readable name for the knowledge source.
description	Optional[str]	Detailed description of the knowledge source.
storage_type	str	Storage backend type (currently only 'minio').
status	str	Source status (active/inactive).
created_at	datetime	When the source was created.
updated_at	datetime	When the source was last updated.

AgentKnowledgeLink

Bases: Base

Many-to-many relationship between agents and knowledge sources.

This link table allows agents to mount/unmount knowledge sources. The is_active flag controls whether the source is used in RAG retrieval.

属性：

名称	类型	描述
id	str	Unique link identifier.
agent_id	str	Foreign key to the agent.
source_id	str	Foreign key to the knowledge source.
is_active	bool	Whether this mount is active for retrieval.
priority	int	Priority for mount ordering (higher = more important).
created_at	datetime	When the link was created.
updated_at	datetime	When the link was last updated.

MCPServer

Bases: Base

Registry entry for an outbound MCP server.

属性：

名称	类型	描述
id	str	Unique MCP server identifier.
name	str	Human-readable MCP server name.
description	Optional[str]	Optional server description.
status	str	MCP server status.
transport_type	str	Transport type (stdio or http_sse).
connection_config_json	str	Non-sensitive connection metadata JSON.
credential_schema_json	Optional[str]	Credential schema definition JSON.
health_status	Optional[str]	Last health check status.
last_health_check_at	Optional[datetime]	Last health-check timestamp.
created_at	datetime	Creation timestamp.
updated_at	datetime	Last update timestamp.

MCPCredential

Bases: Base

Encrypted credentials for an MCP server.

属性：

名称	类型	描述
id	str	Unique credential identifier.
mcp_server_id	str	Foreign key to MCP server.
scope_type	str	Isolation scope type.
scope_id	Optional[str]	Scope identifier for user/team records.
credential_label	str	Human-readable credential label.
encrypted_secret_json	str	Encrypted credential payload.
encryption_key_id	str	Encryption key version identifier.
created_by	Optional[str]	Actor that created the credential.
created_at	datetime	Creation timestamp.
updated_at	datetime	Last update timestamp.
rotated_at	Optional[datetime]	Last rotation timestamp.

AgentMCPLink

Bases: Base

Many-to-many relationship between agents and outbound MCP servers.

属性：

名称	类型	描述
id	str	Unique mount identifier.
agent_id	str	Agent identifier.
mcp_server_id	str	MCP server identifier.
credential_id	Optional[str]	Bound credential identifier.
is_active	bool	Whether this mount is active.
priority	int	Priority for mount ordering.
allowed_tools_json	Optional[str]	Tool allowlist JSON.
tool_capability	Optional[str]	Admin-declared business capability label.
timeout_ms	int	Per-call timeout in milliseconds.
max_calls_per_turn	int	Max tool calls per turn.
created_at	datetime	Creation timestamp.
updated_at	datetime	Last update timestamp.

MCPCallAudit

Bases: Base

Audit record for MCP tool invocations.

属性：

名称	类型	描述
id	str	Unique audit identifier.
session_id	str	Session identifier.
agent_id	str	Agent identifier.
mcp_server_id	str	MCP server identifier.
credential_id	Optional[str]	Credential identifier used in the call.
trace_id	Optional[str]	Shared trace identifier for turn correlation.
tool_name	str	Invoked tool name.
request_payload_json	Optional[str]	Redacted request payload JSON.
response_payload_json	Optional[str]	Redacted response payload JSON.
status	str	Invocation status.
latency_ms	Optional[int]	Invocation latency in milliseconds.
error_message	Optional[str]	Error details when failed.
created_at	datetime	Creation timestamp.

Document

Bases: Base

Represents a document uploaded to a knowledge source.

Documents are stored in MinIO and processed through the ingestion pipeline to create chunks and embeddings for RAG retrieval.

属性：

名称	类型	描述
id	str	Unique document identifier.
source_id	str	Foreign key to the knowledge source.
filename	str	Original filename of the uploaded document.
content_type	str	MIME type of the document.
size_bytes	int	File size in bytes.
minio_object_key	str	Object key in MinIO storage.
status	str	Document processing status.
vector_status	str	Retrieval/vector health status.
expected_point_count	Optional[int]	Expected point count in Qdrant.
actual_point_count	Optional[int]	Last verified point count in Qdrant.
vector_verified_at	Optional[datetime]	When vector health was last verified.
error_message	Optional[str]	Error message if processing failed.
metadata_json	Optional[str]	Additional metadata as JSON string.
created_at	datetime	When the document was uploaded.
updated_at	datetime	When the document was last updated.

DocumentChunk

Bases: Base

Represents a text chunk extracted from a document for RAG retrieval.

Document chunks are the atomic units for vector search. Each chunk contains text content and is associated with an agent and knowledge source for metadata-based filtering during retrieval.

属性：

名称	类型	描述
id	str	Unique chunk identifier.
source_id	str	Foreign key to the knowledge source.
agent_id	Optional[str]	Foreign key to the agent (for direct filtering).
document_name	str	Original document filename or identifier.
chunk_index	int	Position of this chunk within the document.
content	str	Text content of the chunk.
metadata_json	Optional[str]	Additional metadata as JSON string.
created_at	datetime	When the chunk was created.

IngestionJob

Bases: Base

Represents an ingestion job for processing documents.

Ingestion jobs track the progress of document processing, including parsing, chunking, embedding, and indexing.

属性：

名称	类型	描述
id	str	Unique job identifier.
source_id	str	Foreign key to the knowledge source.
agent_id	Optional[str]	Optional agent ID for scoped ingestion.
status	str	Job status (queued/running/succeeded/failed).
documents_total	int	Total number of documents to process.
documents_done	int	Number of documents processed.
chunks_total	int	Total number of chunks created.
chunks_done	int	Number of chunks indexed.
chunk_size	int	Chunk size used for this job.
chunk_overlap	int	Chunk overlap used for this job.
embedding_model	str	Embedding model used for this job.
error_message	Optional[str]	Error message if job failed.
status_message	Optional[str]	Current processing stage description.
created_at	datetime	When the job was created.
updated_at	datetime	When the job was last updated.

ScheduledTask

Bases: Base

Represents one durable scheduled task created from conversation.

ScheduledTaskRun

Bases: Base

Represents one durable execution attempt for a scheduled task.

AgentEvaluationRun

Bases: Base

Represents one asynchronous evaluation run for an agent.

属性：

名称	类型	描述
id	str	Run identifier.
agent_id	str	Evaluated agent id.
agent_version_id	Optional[str]	Immutable agent snapshot identifier used to reproduce this run.
dataset_id	str	Dataset used by this run.
status	str	Run lifecycle status.
triggered_by	Optional[str]	Optional actor identifier.
model_name	Optional[str]	Model snapshot used for this run.
model_provider	Optional[str]	Provider snapshot used for this run.
model_temperature	Optional[float]	Temperature snapshot used for this run.
model_routing_config_json	Optional[str]	Role-based model routing snapshot used for this run.
items_total	int	Total number of dataset items.
items_done	int	Number of processed items.
score_em	Optional[float]	Exact match score.
score_f1	Optional[float]	Token-level F1 score.
score_pass_rate	Optional[float]	Pass rate score.
score_llm_judge	Optional[float]	LLM judge score.
generation_input_tokens	Optional[int]	Run-level generation prompt tokens.
generation_output_tokens	Optional[int]	Run-level generation output tokens.
generation_total_tokens	Optional[int]	Run-level generation total tokens.
generation_usage_breakdown_json	Optional[str]	Run-level generation source-quality counters.
judge_input_tokens	Optional[int]	Run-level judge prompt tokens.
judge_output_tokens	Optional[int]	Run-level judge output tokens.
judge_total_tokens	Optional[int]	Run-level judge total tokens.
judge_usage_breakdown_json	Optional[str]	Run-level judge source-quality counters.
attempt_count	int	Number of worker attempts that have claimed this run.
lease_token	Optional[str]	Active worker lease token for the current claim.
last_attempt_started_at	Optional[datetime]	Timestamp of the latest claim.
worker_heartbeat_at	Optional[datetime]	Latest worker heartbeat timestamp.
judge_model_name	Optional[str]	Judge model snapshot used for this run.
judge_model_provider	Optional[str]	Judge provider snapshot used for this run.
judge_prompt_version	Optional[str]	Judge rubric/prompt snapshot used for this run.
judge_prompt_text	Optional[str]	Judge prompt text snapshot used for this run.
gating_status	str	Run gate decision status.
gating_policy_json	Optional[str]	Serialized gate policy snapshot.
failed_criteria_json	Optional[str]	Serialized failed criteria list.
error_message	Optional[str]	Error details when run fails.
started_at	Optional[datetime]	Run start timestamp.
completed_at	Optional[datetime]	Run completion timestamp.
created_at	datetime	Creation timestamp.
updated_at	datetime	Last update timestamp.

AgentEvaluationResult

Bases: Base

Represents one evaluated item result inside a run.

属性：

名称	类型	描述
id	str	Result identifier.
run_id	str	Parent run identifier.
dataset_item_id	str	Evaluated dataset item id.
status	str	Item evaluation status.
prediction_json	Optional[str]	Prediction payload JSON.
rule_score_json	Optional[str]	Rule-based score payload JSON.
judge_score_json	Optional[str]	LLM-judge score payload JSON.
generation_input_tokens	Optional[int]	Generation prompt tokens.
generation_output_tokens	Optional[int]	Generation output tokens.
generation_total_tokens	Optional[int]	Generation total tokens.
generation_usage_source	Optional[str]	Generation usage provenance marker.
judge_input_tokens	Optional[int]	Judge prompt tokens.
judge_output_tokens	Optional[int]	Judge output tokens.
judge_total_tokens	Optional[int]	Judge total tokens.
judge_usage_source	Optional[str]	Judge usage provenance marker.
latency_ms	Optional[int]	Item evaluation latency.
error_message	Optional[str]	Error details when item fails.
created_at	datetime	Creation timestamp.

create_session_record

create_session_record(
    db_session, *, session_id=None, status
)

Create a new session row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	Optional[str]	Optional fixed session id.	None
status	str	Initial session status.	必需

返回：

名称	类型	描述
Session	Session	The created session row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

get_session_record

get_session_record(db_session, session_id)

Fetch a session row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Session identifier.	必需

返回：

类型	描述
Optional[Session]	Optional[Session]: Matching session row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_or_create_session_record

get_or_create_session_record(
    db_session, *, session_id, status
)

Get or create a session row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Desired session identifier.	必需
status	str	Initial session status if created.	必需

返回：

名称	类型	描述
Session	Session	Existing or newly created session row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

update_session_status

update_session_status(
    db_session, *, session_record, status
)

Update session status and timestamp.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_record	Session	Session to update.	必需
status	str	New session status.	必需

返回：

名称	类型	描述
Session	Session	Updated session row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

activate_session_takeover

activate_session_takeover(
    db_session,
    *,
    session_record,
    operator_id_snapshot,
    operator_name_snapshot=None,
    takeover_started_at=None,
)

Mark one session as human-controlled and persist owner snapshots.

release_session_takeover

release_session_takeover(
    db_session, *, session_record, takeover_released_at=None
)

Clear one session takeover owner and return control to AI.

update_session_model_config

update_session_model_config(
    db_session,
    *,
    session_record,
    model_name,
    model_provider,
    model_temperature,
)

Update the session model configuration and timestamp.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_record	Session	Session to update.	必需
model_name	Optional[str]	Selected model name.	必需
model_provider	Optional[str]	Selected model provider.	必需
model_temperature	Optional[float]	Selected model temperature.	必需

返回：

名称	类型	描述
Session	Session	Updated session row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

touch_session_record

touch_session_record(db_session, *, session_record)

Update session timestamp to mark activity.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_record	Session	Session to update.	必需

返回：

名称	类型	描述
Session	Session	Updated session row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_session_records

list_session_records(
    db_session,
    *,
    limit=50,
    agent_id=None,
    query_text=None,
    date_from=None,
    date_to=None,
    cursor_updated_at=None,
    cursor_id=None,
)

List sessions ordered by recency with optional filters.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
limit	int	Max number of sessions.	50
agent_id	Optional[str]	Optional agent filter.	None
query_text	Optional[str]	Optional free-text query over session id/messages.	None
date_from	Optional[datetime]	Optional inclusive lower bound by update time.	None
date_to	Optional[datetime]	Optional inclusive upper bound by update time.	None
cursor_updated_at	Optional[datetime]	Cursor updated timestamp.	None
cursor_id	Optional[str]	Cursor session id as tie-breaker.	None

返回：

类型	描述
list[Session]	list[Session]: Session rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

create_message_record

create_message_record(
    db_session,
    *,
    session_id,
    role,
    content,
    sender_id_snapshot=None,
    sender_name_snapshot=None,
)

Create a message row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Owning session id.	必需
role	str	Message role.	必需
content	str	Message content.	必需
sender_id_snapshot	Optional[str]	Manual sender/operator identifier.	None
sender_name_snapshot	Optional[str]	Manual sender/operator name.	None

返回：

名称	类型	描述
Message	Message	Created message row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_message_records

list_message_records(db_session, *, session_id, limit=200)

List recent messages for a session.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Session identifier.	必需
limit	int	Max number of messages.	200

返回：

类型	描述
list[Message]	list[Message]: Message rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

create_session_takeover_event_record

create_session_takeover_event_record(
    db_session,
    *,
    session_id,
    event_type,
    operator_id_snapshot=None,
    operator_name_snapshot=None,
    payload_json=None,
)

Create one durable takeover audit event row.

list_session_takeover_event_records

list_session_takeover_event_records(
    db_session, *, session_id, limit=100
)

List durable takeover audit events for one session oldest first.

batch_create_message_records

batch_create_message_records(db_session, *, messages)

Persist multiple message records at once.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
messages	Iterable[Message]	Message rows to persist.	必需

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

create_conversation_turn_record

create_conversation_turn_record(
    db_session,
    *,
    session_id,
    agent_id,
    agent_id_snapshot,
    agent_name_snapshot,
    user_id=None,
    trace_id,
    user_message_id,
    assistant_message_id,
    message_type,
    model_name,
    model_provider,
    model_temperature,
    input_tokens=None,
    output_tokens=None,
    total_tokens=None,
    token_usage_source=None,
    exclude_from_request_limits=False,
    started_at,
    completed_at,
    turn_id=None,
)

Create one turn-level observability record.

get_conversation_turn_record

get_conversation_turn_record(db_session, *, turn_id)

Fetch one turn record by id.

list_conversation_turn_records

list_conversation_turn_records(
    db_session,
    *,
    session_id,
    limit=100,
    cursor_created_at=None,
    cursor_id=None,
)

List turn records for one session with cursor pagination.

list_conversation_turn_records_by_ids

list_conversation_turn_records_by_ids(
    db_session, *, turn_id_list
)

Fetch a bounded set of turn rows by identifier.

create_turn_context_snapshot_record

create_turn_context_snapshot_record(
    db_session,
    *,
    turn_id,
    system_prompt_preview,
    effective_input_preview,
    prompt_hash,
    context_payload_json,
    rag_context_json,
    skill_context_json,
    mcp_context_json,
    redaction_policy_version,
    snapshot_id=None,
)

Create one context snapshot record for a turn.

get_turn_context_snapshot_record

get_turn_context_snapshot_record(db_session, *, turn_id)

Fetch one context snapshot by turn id.

count_conversation_turns_by_session_ids

count_conversation_turns_by_session_ids(
    db_session, *, session_id_list
)

Count turn rows per session id.

create_agent_record

create_agent_record(
    db_session,
    *,
    name,
    description=None,
    agent_type=AgentType.CHAT.value,
    system_prompt=None,
    model_name=None,
    model_provider=None,
    model_temperature=None,
    public_access_mode=AgentPublicAccessMode.ADMIN_ONLY.value,
    model_routing_config_json=None,
    human_takeover_enabled=False,
    hide_rag_source_filename=False,
    orchestrator_key=None,
    judge_prompt=None,
    message_type_response_config_json=None,
    mcp_response_config_json=None,
    mcp_runtime_config_json=None,
    response_grounding_config_json=None,
    fusion_input_contract_json=None,
    fusion_output_contract_json=None,
    fusion_execution_policy_json=None,
    fusion_prompting_config_json=None,
    fusion_capability_bindings_json=None,
    fusion_ui_config_json=None,
    published_agent_version_id=None,
    default_chunking_strategy=None,
    default_chunking_params_json=None,
    max_concurrent_requests=None,
    max_total_requests=None,
    max_requests_per_day=None,
    max_total_tokens_daily=None,
    max_total_tokens_monthly=None,
    max_cost_usd_daily=None,
    max_cost_usd_monthly=None,
    max_tool_calls_total_per_request=None,
    max_requests_per_day_per_user=None,
    max_requests_per_month_per_user=None,
    limit_reached_message=None,
    agent_id=None,
)

Create a new agent row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
name	str	Agent name.	必需
description	Optional[str]	Agent description.	None
agent_type	str	Agent type identifier (chat, etl).	CHAT.value
system_prompt	Optional[str]	System prompt for the agent.	None
model_name	Optional[str]	Default model name for the agent.	None
model_provider	Optional[str]	Default model provider for the agent.	None
model_temperature	Optional[float]	Default model temperature for the agent.	None
public_access_mode	str	Public access mode for public runtime routes.	ADMIN_ONLY.value
model_routing_config_json	Optional[str]	JSON config for chat-agent role-based model routing.	None
human_takeover_enabled	bool	Whether manual chat takeover is enabled.	False
hide_rag_source_filename	bool	Whether chat RAG prompt injection hides source filenames from the LLM-facing context text.	False
orchestrator_key	Optional[str]	Chat orchestrator runtime selection key.	None
judge_prompt	Optional[str]	Agent-level Judge prompt override.	None
message_type_response_config_json	Optional[str]	JSON config for message_type-based fixed responses.	None
mcp_response_config_json	Optional[str]	JSON config for Agent-level MCP direct-response and quick-match rules.	None
mcp_runtime_config_json	Optional[str]	JSON config for Agent-level MCP runtime strategy overrides.	None
response_grounding_config_json	Optional[str]	JSON config for Agent-level final-response grounding policy.	None
default_chunking_strategy	Optional[str]	Default chunking strategy identifier for this agent.	None
default_chunking_params_json	Optional[str]	Default chunking parameters as JSON string.	None
max_concurrent_requests	Optional[int]	Optional active chat request cap.	None
max_total_requests	Optional[int]	Optional cumulative chat turn cap.	None
max_requests_per_day	Optional[int]	Optional current-day persisted chat turn cap.	None
max_total_tokens_daily	Optional[int]	Optional current-day token cap.	None
max_total_tokens_monthly	Optional[int]	Optional current-month token cap.	None
max_cost_usd_daily	Optional[float]	Optional current-day estimated cost cap.	None
max_cost_usd_monthly	Optional[float]	Optional current-month estimated cost cap.	None
max_tool_calls_total_per_request	Optional[int]	Optional per-request total tool execution cap.	None
max_requests_per_day_per_user	Optional[int]	Optional per-user daily request cap.	None
max_requests_per_month_per_user	Optional[int]	Optional per-user monthly request cap.	None
limit_reached_message	Optional[str]	Optional custom reply when any limit is reached.	None
agent_id	Optional[str]	Optional fixed agent id.	None

返回：

名称	类型	描述
Agent	Agent	The created agent row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_agent_records

list_agent_records(db_session, *, limit=100)

List agents ordered by creation time.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
limit	int	Max number of agents.	100

返回：

类型	描述
list[Agent]	list[Agent]: Agent rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_agent_record

get_agent_record(db_session, agent_id)

Fetch an agent row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需

返回：

类型	描述
Optional[Agent]	Optional[Agent]: Matching agent row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

update_agent_record

update_agent_record(
    db_session,
    *,
    agent_record,
    name=_UNSET,
    description=_UNSET,
    status=_UNSET,
    agent_type=_UNSET,
    system_prompt=_UNSET,
    model_name=_UNSET,
    model_provider=_UNSET,
    model_temperature=_UNSET,
    public_access_mode=_UNSET,
    model_routing_config_json=_UNSET,
    human_takeover_enabled=_UNSET,
    hide_rag_source_filename=_UNSET,
    orchestrator_key=_UNSET,
    judge_prompt=_UNSET,
    message_type_response_config_json=_UNSET,
    mcp_response_config_json=_UNSET,
    mcp_runtime_config_json=_UNSET,
    response_grounding_config_json=_UNSET,
    fusion_input_contract_json=_UNSET,
    fusion_output_contract_json=_UNSET,
    fusion_execution_policy_json=_UNSET,
    fusion_prompting_config_json=_UNSET,
    fusion_capability_bindings_json=_UNSET,
    fusion_ui_config_json=_UNSET,
    published_agent_version_id=_UNSET,
    default_chunking_strategy=_UNSET,
    default_chunking_params_json=_UNSET,
    max_concurrent_requests=_UNSET,
    max_total_requests=_UNSET,
    max_requests_per_day=_UNSET,
    max_total_tokens_daily=_UNSET,
    max_total_tokens_monthly=_UNSET,
    max_cost_usd_daily=_UNSET,
    max_cost_usd_monthly=_UNSET,
    max_tool_calls_total_per_request=_UNSET,
    max_requests_per_day_per_user=_UNSET,
    max_requests_per_month_per_user=_UNSET,
    limit_reached_message=_UNSET,
)

Update an agent's fields.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_record	Agent	Agent to update.	必需
name	Optional[str]	New name, if provided.	_UNSET
description	Optional[str]	New description, if provided.	_UNSET
status	Optional[str]	New status, if provided.	_UNSET
agent_type	Optional[str]	New agent type, if provided.	_UNSET
system_prompt	Optional[str]	New system prompt, if provided.	_UNSET
model_name	Optional[str]	New model name, if provided.	_UNSET
model_provider	Optional[str]	New model provider, if provided.	_UNSET
model_temperature	Optional[float]	New model temperature, if provided.	_UNSET
public_access_mode	Optional[str]	New public access mode, if provided.	_UNSET
model_routing_config_json	Optional[str]	New JSON config for chat-agent role-based model routing, if provided.	_UNSET
human_takeover_enabled	bool	New human takeover toggle, if provided.	_UNSET
hide_rag_source_filename	bool	New RAG filename-visibility toggle, if provided.	_UNSET
orchestrator_key	Optional[str]	New chat orchestrator runtime key, if provided.	_UNSET
judge_prompt	Optional[str]	New Judge prompt text, if provided.	_UNSET
message_type_response_config_json	Optional[str]	New JSON config for message_type-based fixed responses, if provided.	_UNSET
mcp_response_config_json	Optional[str]	New JSON config for Agent-level MCP direct-response and quick-match rules, if provided.	_UNSET
mcp_runtime_config_json	Optional[str]	New JSON config for Agent-level MCP runtime strategy overrides, if provided.	_UNSET
response_grounding_config_json	Optional[str]	New JSON config for Agent-level final-response grounding policy, if provided.	_UNSET
default_chunking_strategy	Optional[str]	New default chunking strategy, if provided.	_UNSET
default_chunking_params_json	Optional[str]	New default chunking params JSON, if provided.	_UNSET
max_concurrent_requests	Optional[int]	New active chat request cap, if provided.	_UNSET
max_total_requests	Optional[int]	New cumulative chat turn cap, if provided.	_UNSET
max_requests_per_day	Optional[int]	New current-day persisted chat turn cap, if provided.	_UNSET
max_total_tokens_daily	Optional[int]	New current-day token cap, if provided.	_UNSET
max_total_tokens_monthly	Optional[int]	New current-month token cap, if provided.	_UNSET
max_cost_usd_daily	Optional[float]	New current-day estimated cost cap, if provided.	_UNSET
max_cost_usd_monthly	Optional[float]	New current-month estimated cost cap, if provided.	_UNSET
max_tool_calls_total_per_request	Optional[int]	New per-request total tool execution cap, if provided.	_UNSET
max_requests_per_day_per_user	Optional[int]	New per-user daily request cap, if provided.	_UNSET
max_requests_per_month_per_user	Optional[int]	New per-user monthly request cap, if provided.	_UNSET
limit_reached_message	Optional[str]	New custom reply text for limit violations, if provided.	_UNSET

返回：

名称	类型	描述
Agent	Agent	Updated agent row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

resolve_agent_takeover_enabled_by_agent_ids

resolve_agent_takeover_enabled_by_agent_ids(
    db_session, *, agent_id_list
)

Resolve the human-takeover feature flag for provided agent ids.

create_agent_version_record

create_agent_version_record(
    db_session,
    *,
    agent_record,
    snapshot_reason=None,
    created_by=None,
    version_number=None,
    version_id=None,
)

Create a full snapshot record for one agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_record	Agent	Live agent row to snapshot.	必需
snapshot_reason	Optional[str]	Optional snapshot reason note.	None
created_by	Optional[str]	Optional actor identifier.	None
version_number	Optional[int]	Optional fixed version number.	None
version_id	Optional[str]	Optional fixed snapshot id.	None

返回：

名称	类型	描述
AgentVersion	AgentVersion	Created snapshot record.

get_agent_version_record

get_agent_version_record(db_session, version_id)

Fetch an agent snapshot row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
version_id	str	Snapshot identifier.	必需

返回：

类型	描述
Optional[AgentVersion]	Optional[AgentVersion]: Matching snapshot record when found.

list_agent_version_records

list_agent_version_records(
    db_session, *, agent_id, limit=50, offset=0
)

List snapshot rows for one agent, newest version first.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
limit	int	Max number of rows.	50
offset	int	Pagination offset.	0

返回：

类型	描述
list[AgentVersion]	list[AgentVersion]: Snapshot rows.

get_next_agent_version_number

get_next_agent_version_number(db_session, *, agent_id)

Return the next monotonic snapshot version for one agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需

返回：

名称	类型	描述
int	int	Next version number.

create_knowledge_source_record

create_knowledge_source_record(
    db_session,
    *,
    name,
    description=None,
    storage_type=StorageType.MINIO.value,
    source_kind=KnowledgeSourceKind.GENERAL_UPLOAD.value,
    managed_for_agent_id=None,
    source_id=None,
    default_chunking_strategy=ChunkingStrategyType.FIXED_SIZE.value,
    default_chunking_params=None,
)

Create a new knowledge source row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
name	str	Knowledge source name.	必需
description	Optional[str]	Knowledge source description.	None
storage_type	str	Storage backend type.	MINIO.value
source_kind	str	Logical source kind.	GENERAL_UPLOAD.value
managed_for_agent_id	Optional[str]	Agent id when the source is server-managed for one agent.	None
source_id	Optional[str]	Optional fixed source id.	None
default_chunking_strategy	str	Default chunking strategy.	FIXED_SIZE.value
default_chunking_params	Optional[str]	Default chunking params as JSON.	None

返回：

名称	类型	描述
KnowledgeSource	KnowledgeSource	The created knowledge source row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_knowledge_source_records

list_knowledge_source_records(
    db_session, *, limit=100, source_kind=None
)

List knowledge sources ordered by creation time.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
limit	int	Max number of sources.	100
source_kind	Optional[str]	Optional logical source-kind filter.	None

返回：

类型	描述
list[KnowledgeSource]	list[KnowledgeSource]: Knowledge source rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_knowledge_source_record

get_knowledge_source_record(db_session, source_id)

Fetch a knowledge source row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_id	str	Knowledge source identifier.	必需

返回：

类型	描述
Optional[KnowledgeSource]	Optional[KnowledgeSource]: Matching knowledge source row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

update_knowledge_source_record

update_knowledge_source_record(
    db_session,
    *,
    source_record,
    name=None,
    description=None,
    status=None,
    source_kind=None,
    managed_for_agent_id=None,
)

Update a knowledge source's fields.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_record	KnowledgeSource	Knowledge source to update.	必需
name	Optional[str]	New name, if provided.	None
description	Optional[str]	New description, if provided.	None
status	Optional[str]	New status, if provided.	None
source_kind	Optional[str]	New source kind, if provided.	None
managed_for_agent_id	Optional[str]	Managed agent id, if provided.	None

返回：

名称	类型	描述
KnowledgeSource	KnowledgeSource	Updated knowledge source row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

create_agent_knowledge_link

create_agent_knowledge_link(
    db_session,
    *,
    agent_id,
    source_id,
    is_active=True,
    priority=0,
)

Mount a knowledge source to an agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
source_id	str	Knowledge source identifier.	必需
is_active	bool	Whether the mount is active for retrieval.	True
priority	int	Priority for mount ordering (0-100).	0

返回：

名称	类型	描述
AgentKnowledgeLink	AgentKnowledgeLink	The created link row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

delete_agent_knowledge_link

delete_agent_knowledge_link(
    db_session,
    *,
    mount_id=None,
    agent_id=None,
    source_id=None,
)

Unmount a knowledge source from an agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mount_id	Optional[str]	Canonical mount identifier. When provided, this is the preferred delete path.	None
agent_id	Optional[str]	Agent identifier required by the legacy compatibility path.	None
source_id	Optional[str]	Knowledge source identifier required by the legacy compatibility path.	None

返回：

名称	类型	描述
bool	bool	True if a link was deleted, False if not found.

引发：

类型	描述
ValueError	If neither mount_id nor the compatibility pair agent_id + source_id is provided.
SQLAlchemyError	If the database commit fails.

list_agent_knowledge_links

list_agent_knowledge_links(
    db_session, *, agent_id, active_only=False
)

List knowledge sources mounted to an agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
active_only	bool	If True, only return active mounts.	False

返回：

类型	描述
list[AgentKnowledgeLink]	list[AgentKnowledgeLink]: Link rows for the agent.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_agent_knowledge_link

get_agent_knowledge_link(
    db_session, *, agent_id, source_id
)

Fetch an agent-knowledge link by agent and source id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
source_id	str	Knowledge source identifier.	必需

返回：

类型	描述
Optional[AgentKnowledgeLink]	Optional[AgentKnowledgeLink]: Matching link row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_agent_knowledge_link_by_id

get_agent_knowledge_link_by_id(db_session, mount_id)

Fetch an agent-knowledge link by mount id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mount_id	str	Mount identifier.	必需

返回：

类型	描述
Optional[AgentKnowledgeLink]	Optional[AgentKnowledgeLink]: Matching link row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

create_mcp_server_record

create_mcp_server_record(
    db_session,
    *,
    name,
    description,
    status,
    transport_type,
    connection_config_json,
    credential_schema_json,
    mcp_server_id=None,
)

Create a new MCP server registry record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
name	str	MCP server name.	必需
description	Optional[str]	Optional server description.	必需
status	str	MCP server status.	必需
transport_type	str	Transport type.	必需
connection_config_json	str	Non-sensitive connection config JSON.	必需
credential_schema_json	Optional[str]	Credential schema JSON.	必需
mcp_server_id	Optional[str]	Optional fixed server ID.	None

返回：

名称	类型	描述
MCPServer	MCPServer	The created MCP server record.

list_mcp_server_records

list_mcp_server_records(
    db_session, *, include_inactive=True, limit=200
)

List MCP server records.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
include_inactive	bool	Whether to include inactive servers.	True
limit	int	Maximum number of records.	200

返回：

类型	描述
list[MCPServer]	list[MCPServer]: MCP server records.

get_mcp_server_record

get_mcp_server_record(db_session, mcp_server_id)

Fetch an MCP server record by ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mcp_server_id	str	MCP server identifier.	必需

返回：

类型	描述
Optional[MCPServer]	Optional[MCPServer]: Matching record if found, else None.

update_mcp_server_record

update_mcp_server_record(
    db_session,
    *,
    mcp_server_record,
    name=None,
    description=None,
    status=None,
    transport_type=None,
    connection_config_json=None,
    credential_schema_json=None,
    health_status=None,
    health_check_timestamp=None,
)

Update fields of an MCP server record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mcp_server_record	MCPServer	Record to update.	必需
name	Optional[str]	New name.	None
description	Optional[str]	New description.	None
status	Optional[str]	New status.	None
transport_type	Optional[str]	New transport type.	None
connection_config_json	Optional[str]	New connection config JSON.	None
credential_schema_json	Optional[str]	New credential schema JSON.	None
health_status	Optional[str]	Health-check status value.	None
health_check_timestamp	Optional[datetime]	Health-check timestamp.	None

返回：

名称	类型	描述
MCPServer	MCPServer	Updated record.

delete_mcp_server_record

delete_mcp_server_record(db_session, *, mcp_server_id)

Delete an MCP server record by ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mcp_server_id	str	MCP server identifier.	必需

返回：

名称	类型	描述
bool	bool	True when deleted, otherwise False.

create_mcp_credential_record

create_mcp_credential_record(
    db_session,
    *,
    mcp_server_id,
    scope_type,
    scope_id,
    credential_label,
    encrypted_secret_json,
    encryption_key_id,
    created_by,
    credential_id=None,
)

Create an encrypted MCP credential record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mcp_server_id	str	MCP server identifier.	必需
scope_type	str	Credential scope type.	必需
scope_id	Optional[str]	Scope identifier.	必需
credential_label	str	Human-readable label.	必需
encrypted_secret_json	str	Encrypted secret payload JSON.	必需
encryption_key_id	str	Encryption key version identifier.	必需
created_by	Optional[str]	Credential creator identifier.	必需
credential_id	Optional[str]	Optional fixed credential ID.	None

返回：

名称	类型	描述
MCPCredential	MCPCredential	Created credential record.

list_mcp_credential_records

list_mcp_credential_records(
    db_session,
    *,
    mcp_server_id=None,
    scope_type=None,
    scope_id=None,
    limit=200,
)

List MCP credential records with optional filtering.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mcp_server_id	Optional[str]	Optional server filter.	None
scope_type	Optional[str]	Optional scope type filter.	None
scope_id	Optional[str]	Optional scope identifier filter.	None
limit	int	Maximum number of records.	200

返回：

类型	描述
list[MCPCredential]	list[MCPCredential]: Matching credential records.

get_mcp_credential_record

get_mcp_credential_record(db_session, credential_id)

Fetch an MCP credential record by ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
credential_id	str	Credential identifier.	必需

返回：

类型	描述
Optional[MCPCredential]	Optional[MCPCredential]: Matching credential record, if any.

update_mcp_credential_record

update_mcp_credential_record(
    db_session,
    *,
    credential_record,
    scope_type=None,
    scope_id=None,
    credential_label=None,
    encrypted_secret_json=None,
    encryption_key_id=None,
    rotated_at=None,
)

Update fields of an MCP credential record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
credential_record	MCPCredential	Credential to update.	必需
scope_type	Optional[str]	New scope type.	None
scope_id	Optional[str]	New scope identifier.	None
credential_label	Optional[str]	New display label.	None
encrypted_secret_json	Optional[str]	New encrypted payload JSON.	None
encryption_key_id	Optional[str]	New key version identifier.	None
rotated_at	Optional[datetime]	Rotation timestamp.	None

返回：

名称	类型	描述
MCPCredential	MCPCredential	Updated credential record.

delete_mcp_credential_record

delete_mcp_credential_record(db_session, *, credential_id)

Delete an MCP credential by ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
credential_id	str	Credential identifier.	必需

返回：

名称	类型	描述
bool	bool	True when deleted, otherwise False.

create_agent_mcp_link

create_agent_mcp_link(
    db_session,
    *,
    agent_id,
    mcp_server_id,
    credential_id,
    is_active,
    priority,
    allowed_tools_json,
    tool_capability,
    timeout_ms,
    max_calls_per_turn,
    link_id=None,
)

Create an agent-to-MCP-server mount record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
mcp_server_id	str	MCP server identifier.	必需
credential_id	Optional[str]	Bound credential identifier.	必需
is_active	bool	Mount active flag.	必需
priority	int	Mount priority.	必需
allowed_tools_json	Optional[str]	Tool allowlist JSON.	必需
tool_capability	Optional[str]	Admin-declared business capability label.	必需
timeout_ms	int	Per-call timeout in milliseconds.	必需
max_calls_per_turn	int	Max calls per turn.	必需
link_id	Optional[str]	Optional fixed link ID.	None

返回：

名称	类型	描述
AgentMCPLink	AgentMCPLink	Created mount record.

list_agent_mcp_links

list_agent_mcp_links(
    db_session, *, agent_id, active_only=False
)

List MCP mounts for an agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
active_only	bool	Whether to only include active mounts.	False

返回：

类型	描述
list[AgentMCPLink]	list[AgentMCPLink]: Agent MCP mount records.

get_agent_mcp_link

get_agent_mcp_link(db_session, *, agent_id, mcp_server_id)

Fetch an agent MCP mount by agent and server IDs.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
mcp_server_id	str	MCP server identifier.	必需

返回：

类型	描述
Optional[AgentMCPLink]	Optional[AgentMCPLink]: Matching mount record if found.

get_agent_mcp_link_by_id

get_agent_mcp_link_by_id(db_session, mount_id)

Fetch an agent MCP mount by mount ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mount_id	str	Mount identifier.	必需

返回：

类型	描述
Optional[AgentMCPLink]	Optional[AgentMCPLink]: Matching mount record if found.

update_agent_mcp_link

update_agent_mcp_link(
    db_session,
    *,
    link_record,
    credential_id=_UNSET_MCP_LINK_FIELD,
    is_active=None,
    priority=None,
    allowed_tools_json=_UNSET_MCP_LINK_FIELD,
    tool_capability=_UNSET_MCP_LINK_FIELD,
    timeout_ms=None,
    max_calls_per_turn=None,
)

Update fields of an agent MCP mount record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
link_record	AgentMCPLink	Mount record to update.	必需
credential_id	Optional[str] | object	Bound credential identifier.	_UNSET_MCP_LINK_FIELD
is_active	Optional[bool]	Active flag.	None
priority	Optional[int]	Priority value.	None
allowed_tools_json	Optional[str] | object	Tool allowlist JSON.	_UNSET_MCP_LINK_FIELD
tool_capability	Optional[str] | object	Admin-declared business capability label.	_UNSET_MCP_LINK_FIELD
timeout_ms	Optional[int]	Per-call timeout in milliseconds.	None
max_calls_per_turn	Optional[int]	Max calls per turn.	None

返回：

名称	类型	描述
AgentMCPLink	AgentMCPLink	Updated mount record.

delete_agent_mcp_link

delete_agent_mcp_link(db_session, *, mount_id)

Delete an agent MCP mount by mount ID.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
mount_id	str	Mount identifier.	必需

返回：

名称	类型	描述
bool	bool	True when deleted, otherwise False.

create_mcp_call_audit_record

create_mcp_call_audit_record(
    db_session,
    *,
    session_id,
    agent_id,
    mcp_server_id,
    credential_id,
    trace_id,
    tool_name,
    request_payload_json,
    response_payload_json,
    status,
    latency_ms,
    error_message,
    audit_id=None,
)

Create an MCP call audit record.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Session identifier.	必需
agent_id	str	Agent identifier.	必需
mcp_server_id	str	MCP server identifier.	必需
credential_id	Optional[str]	Credential identifier used for call.	必需
trace_id	Optional[str]	Optional trace identifier.	必需
tool_name	str	Tool name.	必需
request_payload_json	Optional[str]	Redacted request payload JSON.	必需
response_payload_json	Optional[str]	Redacted response payload JSON.	必需
status	str	Invocation status.	必需
latency_ms	Optional[int]	Latency in milliseconds.	必需
error_message	Optional[str]	Error details.	必需
audit_id	Optional[str]	Optional fixed audit ID.	None

返回：

名称	类型	描述
MCPCallAudit	MCPCallAudit	Created audit record.

list_mcp_call_audits_by_session

list_mcp_call_audits_by_session(
    db_session, *, session_id, limit=200
)

List MCP call audits for a session.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Session identifier.	必需
limit	int	Maximum number of records.	200

返回：

类型	描述
list[MCPCallAudit]	list[MCPCallAudit]: Session audit records.

list_mcp_call_audits_by_agent

list_mcp_call_audits_by_agent(
    db_session, *, agent_id, limit=200
)

List MCP call audits for an agent.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Agent identifier.	必需
limit	int	Maximum number of records.	200

返回：

类型	描述
list[MCPCallAudit]	list[MCPCallAudit]: Agent audit records.

list_mcp_call_audits_by_trace_id

list_mcp_call_audits_by_trace_id(
    db_session, *, trace_id, limit=200
)

List MCP call audits for one trace id.

create_document_record

create_document_record(
    db_session,
    *,
    source_id,
    filename,
    content_type,
    size_bytes,
    minio_object_key,
    metadata_json=None,
    document_id=None,
)

Create a new document row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_id	str	Knowledge source identifier.	必需
filename	str	Original filename.	必需
content_type	str	MIME type.	必需
size_bytes	int	File size in bytes.	必需
minio_object_key	str	Object key in MinIO.	必需
metadata_json	Optional[str]	Additional metadata as JSON.	None
document_id	Optional[str]	Optional fixed document id.	None

返回：

名称	类型	描述
Document	Document	The created document row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_documents_by_source

list_documents_by_source(
    db_session, *, source_id, limit=1000
)

List documents for a knowledge source.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_id	str	Knowledge source identifier.	必需
limit	int	Max number of documents.	1000

返回：

类型	描述
list[Document]	list[Document]: Document rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_document_record

get_document_record(db_session, document_id)

Fetch a document row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
document_id	str	Document identifier.	必需

返回：

类型	描述
Optional[Document]	Optional[Document]: Matching document row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

delete_document_record

delete_document_record(db_session, *, document_id)

Delete a document row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
document_id	str	Document identifier.	必需

返回：

名称	类型	描述
bool	bool	True if deleted, False if not found.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

create_ingestion_job_record

create_ingestion_job_record(
    db_session,
    *,
    source_id,
    agent_id=None,
    chunk_size=512,
    chunk_overlap=50,
    chunking_strategy=ChunkingStrategyType.FIXED_SIZE.value,
    chunking_params=None,
    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
    job_id=None,
)

Create a new ingestion job row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_id	str	Knowledge source identifier.	必需
agent_id	Optional[str]	Optional agent identifier.	None
chunk_size	int	Chunk size for splitting.	512
chunk_overlap	int	Overlap between chunks.	50
chunking_strategy	str	Chunking strategy to use.	FIXED_SIZE.value
chunking_params	Optional[str]	Chunking parameters as JSON.	None
embedding_model	str	Embedding model name.	'sentence-transformers/all-MiniLM-L6-v2'
job_id	Optional[str]	Optional fixed job id.	None

返回：

名称	类型	描述
IngestionJob	IngestionJob	The created job row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

update_ingestion_job_status

update_ingestion_job_status(
    db_session, *, job_record, status, error_message=None
)

Update an ingestion job's status.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
job_record	IngestionJob	Job to update.	必需
status	str	New status.	必需
error_message	Optional[str]	Error message if status is FAILED.	None

返回：

名称	类型	描述
IngestionJob	IngestionJob	Updated job row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_ingestion_jobs_by_source

list_ingestion_jobs_by_source(
    db_session, *, source_id, limit=100
)

List ingestion jobs for a knowledge source.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
source_id	str	Knowledge source identifier.	必需
limit	int	Max number of jobs.	100

返回：

类型	描述
list[IngestionJob]	list[IngestionJob]: Job rows.

引发：

类型	描述
SQLAlchemyError	If the query fails.

get_ingestion_job_record

get_ingestion_job_record(db_session, job_id)

Fetch an ingestion job row by id.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
job_id	str	Job identifier.	必需

返回：

类型	描述
Optional[IngestionJob]	Optional[IngestionJob]: Matching job row, if any.

引发：

类型	描述
SQLAlchemyError	If the query fails.

create_scheduled_task_record

create_scheduled_task_record(
    db_session,
    *,
    agent_id,
    source_session_id,
    source_turn_id=None,
    created_by_role,
    schedule_kind,
    schedule_payload_json,
    timezone_name,
    target_mode=ScheduledTaskTargetMode.BOUND_SESSION.value,
    payload_kind=ScheduledTaskPayloadKind.PROMPT.value,
    payload_json,
    status=ScheduledTaskStatus.ACTIVE.value,
    conflict_policy=ScheduledTaskConflictPolicy.DEFER.value,
    next_run_at=None,
    task_id=None,
)

Create one scheduled-task row.

get_scheduled_task_record

get_scheduled_task_record(db_session, task_id)

Fetch one scheduled-task row by id.

list_scheduled_task_records

list_scheduled_task_records(
    db_session,
    *,
    agent_id=None,
    session_id=None,
    status=None,
    target_mode=None,
    schedule_kind=None,
    limit=100,
    offset=0,
)

List scheduled-task rows with optional filters.

list_due_scheduled_task_records

list_due_scheduled_task_records(
    db_session, *, due_before, limit=100
)

List active scheduled tasks that are due to fire.

claim_scheduled_task_record

claim_scheduled_task_record(
    db_session,
    *,
    task_id,
    lease_token=None,
    claim_time=None,
)

Claim one due scheduled-task row for execution.

update_scheduled_task_record

update_scheduled_task_record(
    db_session,
    *,
    task_record,
    status=_UNSET,
    schedule_payload_json=_UNSET,
    timezone_name=_UNSET,
    target_mode=_UNSET,
    payload_json=_UNSET,
    conflict_policy=_UNSET,
    next_run_at=_UNSET,
    last_run_at=_UNSET,
    last_successful_run_at=_UNSET,
    lease_token=_UNSET,
    worker_heartbeat_at=_UNSET,
    failure_count=_UNSET,
    updated_at=None,
)

Update one scheduled-task row.

cancel_scheduled_task_record

cancel_scheduled_task_record(db_session, *, task_record)

Cancel one scheduled task idempotently.

touch_scheduled_task_heartbeat

touch_scheduled_task_heartbeat(
    db_session,
    *,
    task_record,
    lease_token=None,
    heartbeat_at=None,
)

Persist one scheduled-task worker heartbeat.

reclaim_stale_scheduled_task_leases

reclaim_stale_scheduled_task_leases(
    db_session, *, stale_before
)

Release stale task leases so due work can be claimed again.

create_scheduled_task_run_record

create_scheduled_task_run_record(
    db_session,
    *,
    task_id,
    scheduled_for,
    status=ScheduledTaskRunStatus.QUEUED.value,
    target_session_id=None,
    conversation_turn_id=None,
    trigger_event_name="scheduled_trigger",
    run_id=None,
)

Create one scheduled-task run row.

get_scheduled_task_run_record

get_scheduled_task_run_record(db_session, run_id)

Fetch one scheduled-task run row by id.

list_scheduled_task_run_records

list_scheduled_task_run_records(
    db_session, *, task_id, limit=100
)

List run rows for one scheduled task.

find_pending_scheduled_task_run

find_pending_scheduled_task_run(
    db_session, *, task_id, scheduled_for
)

Find one queued/running/deferred run for the same task fire time.

claim_scheduled_task_run_record

claim_scheduled_task_run_record(
    db_session, *, run_id, lease_token=None, claim_time=None
)

Claim one queued scheduled-task run row for execution.

update_scheduled_task_run_status

update_scheduled_task_run_status(
    db_session,
    *,
    run_record,
    status,
    target_session_id=_UNSET,
    conversation_turn_id=_UNSET,
    started_at=_UNSET,
    completed_at=_UNSET,
    error_message=_UNSET,
)

Update one scheduled-task run lifecycle row.

touch_scheduled_task_run_heartbeat

touch_scheduled_task_run_heartbeat(
    db_session,
    *,
    run_record,
    lease_token=None,
    heartbeat_at=None,
)

Persist one run heartbeat when the worker still owns the lease.

requeue_stale_scheduled_task_runs

requeue_stale_scheduled_task_runs(
    db_session, *, stale_before, requeue_message=None
)

Move stale RUNNING scheduled-task runs back to QUEUED.

create_agent_evaluation_run_record

create_agent_evaluation_run_record(
    db_session,
    *,
    agent_id,
    agent_version_id=None,
    dataset_id,
    triggered_by=None,
    model_name=None,
    model_provider=None,
    model_temperature=None,
    model_routing_config_json=None,
    judge_model_name=None,
    judge_model_provider=None,
    judge_prompt_version=None,
    judge_prompt_text=None,
    status=EvaluationRunStatus.QUEUED.value,
    items_total=0,
    run_id=None,
)

Create a new agent evaluation run row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_id	str	Evaluated agent identifier.	必需
agent_version_id	Optional[str]	Immutable agent snapshot identifier.	None
dataset_id	str	Dataset identifier.	必需
triggered_by	Optional[str]	Optional actor identifier.	None
model_name	Optional[str]	Model snapshot for this run.	None
model_provider	Optional[str]	Provider snapshot for this run.	None
model_temperature	Optional[float]	Temperature snapshot for this run.	None
model_routing_config_json	Optional[str]	Role-based model routing snapshot for this run.	None
judge_model_name	Optional[str]	Judge model snapshot for this run.	None
judge_model_provider	Optional[str]	Judge provider snapshot for this run.	None
judge_prompt_version	Optional[str]	Judge rubric/prompt snapshot.	None
judge_prompt_text	Optional[str]	Judge prompt text snapshot.	None
status	str	Initial run status.	QUEUED.value
items_total	int	Initial dataset item count.	0
run_id	Optional[str]	Optional fixed run id.	None

返回：

名称	类型	描述
AgentEvaluationRun	AgentEvaluationRun	Created run row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

update_agent_evaluation_run_progress

update_agent_evaluation_run_progress(
    db_session,
    *,
    run_record,
    items_total=None,
    items_done=None,
    score_em=None,
    score_f1=None,
    score_pass_rate=None,
    score_llm_judge=None,
    generation_input_tokens=None,
    generation_output_tokens=None,
    generation_total_tokens=None,
    generation_usage_breakdown_json=None,
    judge_input_tokens=None,
    judge_output_tokens=None,
    judge_total_tokens=None,
    judge_usage_breakdown_json=None,
)

Update progress counters and aggregated scores of a run.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
run_record	AgentEvaluationRun	Run row to update.	必需
items_total	Optional[int]	Total item count.	None
items_done	Optional[int]	Processed item count.	None
score_em	Optional[float]	Exact-match score.	None
score_f1	Optional[float]	Token-level F1 score.	None
score_pass_rate	Optional[float]	Pass-rate score.	None
score_llm_judge	Optional[float]	LLM judge score.	None
generation_input_tokens	Optional[int]	Aggregated generation prompt tokens.	None
generation_output_tokens	Optional[int]	Aggregated generation output tokens.	None
generation_total_tokens	Optional[int]	Aggregated generation total tokens.	None
generation_usage_breakdown_json	Optional[str]	Generation source counters.	None
judge_input_tokens	Optional[int]	Aggregated judge prompt tokens.	None
judge_output_tokens	Optional[int]	Aggregated judge output tokens.	None
judge_total_tokens	Optional[int]	Aggregated judge total tokens.	None
judge_usage_breakdown_json	Optional[str]	Judge source counters.	None

返回：

名称	类型	描述
AgentEvaluationRun	AgentEvaluationRun	Updated run row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

create_agent_evaluation_result_record

create_agent_evaluation_result_record(
    db_session,
    *,
    run_id,
    dataset_item_id,
    status=EvaluationResultStatus.SUCCEEDED.value,
    prediction_json=None,
    rule_score_json=None,
    judge_score_json=None,
    generation_input_tokens=None,
    generation_output_tokens=None,
    generation_total_tokens=None,
    generation_usage_source=None,
    judge_input_tokens=None,
    judge_output_tokens=None,
    judge_total_tokens=None,
    judge_usage_source=None,
    latency_ms=None,
    error_message=None,
    result_id=None,
)

Create one agent evaluation result row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
run_id	str	Parent run identifier.	必需
dataset_item_id	str	Evaluated dataset item identifier.	必需
status	str	Result status.	SUCCEEDED.value
prediction_json	Optional[str]	Prediction payload JSON.	None
rule_score_json	Optional[str]	Rule score payload JSON.	None
judge_score_json	Optional[str]	Judge score payload JSON.	None
generation_input_tokens	Optional[int]	Generation prompt tokens.	None
generation_output_tokens	Optional[int]	Generation output tokens.	None
generation_total_tokens	Optional[int]	Generation total tokens.	None
generation_usage_source	Optional[str]	Generation usage provenance.	None
judge_input_tokens	Optional[int]	Judge prompt tokens.	None
judge_output_tokens	Optional[int]	Judge output tokens.	None
judge_total_tokens	Optional[int]	Judge total tokens.	None
judge_usage_source	Optional[str]	Judge usage provenance.	None
latency_ms	Optional[int]	Evaluation latency.	None
error_message	Optional[str]	Error details when failed.	None
result_id	Optional[str]	Optional fixed result id.	None

返回：

名称	类型	描述
AgentEvaluationResult	AgentEvaluationResult	Created result row.

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

list_all_agent_evaluation_results

list_all_agent_evaluation_results(db_session, *, run_id)

List all item results for one evaluation run.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
run_id	str	Evaluation run identifier.	必需

返回：

类型	描述
list[AgentEvaluationResult]	list[AgentEvaluationResult]: All result rows ordered by creation time.

引发：

类型	描述
SQLAlchemyError	If the query fails.

list_skill_execution_audits_by_trace_id

list_skill_execution_audits_by_trace_id(
    db_session, *, trace_id, limit=200
)

List skill execution audits for one trace id.

MinIO 服务

Service for managing raw documents in MinIO object storage.

This service handles uploading, downloading, and deleting documents in the configured MinIO bucket.

属性：

名称	类型	描述
client	Minio	MinIO client instance.
bucket_name	str	Name of the bucket for raw documents.

__init__

__init__(
    *,
    endpoint=None,
    access_key=None,
    secret_key=None,
    secure=None,
    bucket_name=None,
)

Initialize the MinIO storage service.

参数：

名称	类型	描述	默认
endpoint	Optional[str]	MinIO server endpoint. Defaults to config.	None
access_key	Optional[str]	MinIO access key. Defaults to config.	None
secret_key	Optional[str]	MinIO secret key. Defaults to config.	None
secure	Optional[bool]	Use HTTPS. Defaults to config.	None
bucket_name	Optional[str]	Bucket name. Defaults to config.	None

has_public_download_endpoint

has_public_download_endpoint()

Check whether external endpoint is configured for presigned URLs.

返回：

名称	类型	描述
bool	bool	True when MINIO_PUBLIC_ENDPOINT is configured.

generate_download_url

generate_download_url(*, object_key, expires=None)

Generate a presigned URL for downloading an object.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需
expires	Optional[timedelta]	URL expiration duration. Defaults to config.	None

返回：

名称	类型	描述
str	str	Presigned download URL.

upload_file

upload_file(*, object_key, file_data, content_type, size)

Upload a file to MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需
file_data	BinaryIO	File-like object containing the data.	必需
content_type	str	MIME type of the file.	必需
size	int	Size of the file in bytes.	必需

返回：

名称	类型	描述
str	str	The object key of the uploaded file.

引发：

类型	描述
S3Error	If the upload fails.

upload_bytes

upload_bytes(*, object_key, data, content_type)

Upload bytes data to MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需
data	bytes	Raw bytes to upload.	必需
content_type	str	MIME type of the data.	必需

返回：

名称	类型	描述
str	str	The object key of the uploaded file.

引发：

类型	描述
S3Error	If the upload fails.

download_file

download_file(*, object_key)

Download a file from MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需

返回：

名称	类型	描述
bytes	bytes	The file contents.

引发：

类型	描述
S3Error	If the download fails.

delete_file

delete_file(*, object_key)

Delete a file from MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需

返回：

名称	类型	描述
bool	bool	True if deleted successfully.

引发：

类型	描述
S3Error	If the deletion fails.

file_exists

file_exists(*, object_key)

Check if a file exists in MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需

返回：

名称	类型	描述
bool	bool	True if the file exists.

get_file_info

get_file_info(*, object_key)

Get metadata about a file in MinIO.

参数：

名称	类型	描述	默认
object_key	str	Object key (path) in the bucket.	必需

返回：

名称	类型	描述
dict	dict	File metadata including size, content_type, and last_modified.

引发：

类型	描述
S3Error	If the operation fails.

Qdrant 服务

Service for managing document vectors in Qdrant.

This service handles creating collections, upserting vectors, searching for similar documents, and deleting vectors.

属性：

名称	类型	描述
client	QdrantClient	Qdrant client instance.
collection_name	str	Name of the vector collection.
embedding_dim	int	Dimension of the embedding vectors.

__init__

__init__(
    *,
    host=None,
    port=None,
    collection_name=None,
    embedding_dim=None,
)

Initialize the Qdrant vector service.

参数：

名称	类型	描述	默认
host	Optional[str]	Qdrant server host. Defaults to config.	None
port	Optional[int]	Qdrant server port. Defaults to config.	None
collection_name	Optional[str]	Collection name. Defaults to config.	None
embedding_dim	Optional[int]	Embedding dimension. Defaults to config.	None

upsert_vectors

upsert_vectors(*, ids, vectors, payloads)

Upsert vectors into the collection.

参数：

名称	类型	描述	默认
ids	list[str]	List of unique identifiers for each vector.	必需
vectors	list[list[float]]	List of embedding vectors.	必需
payloads	list[dict[str, Any]]	List of metadata payloads.	必需

返回：

名称	类型	描述
int	int	Number of vectors upserted.

引发：

类型	描述
ValueError	If the input lists have different lengths.
Exception	If the upsert operation fails.

search

search(
    *,
    query_vector,
    top_k=5,
    filter_conditions=None,
    score_threshold=None,
)

Search for similar vectors in the collection.

参数：

名称	类型	描述	默认
query_vector	list[float]	Query embedding vector.	必需
top_k	int	Number of results to return.	5
filter_conditions	Optional[dict[str, Any]]	Filter conditions for search.	None
score_threshold	Optional[float]	Minimum similarity score threshold.	None

返回：

类型	描述
list[dict[str, Any]]	list[dict[str, Any]]: List of search results with id, score, and payload.

引发：

类型	描述
Exception	If the search operation fails.

delete_by_filter

delete_by_filter(
    *, filter_conditions, include_read_collections=False
)

Delete vectors matching the filter conditions.

参数：

名称	类型	描述	默认
filter_conditions	dict[str, Any]	Filter conditions for deletion.	必需
include_read_collections	bool	Whether to also delete matching vectors from configured fallback read collections.	False

返回：

名称	类型	描述
bool	bool	True if deletion was successful.

引发：

类型	描述
Exception	If the deletion operation fails.

delete_by_ids

delete_by_ids(*, ids)

Delete vectors by their IDs.

参数：

名称	类型	描述	默认
ids	list[str]	List of vector IDs to delete.	必需

返回：

名称	类型	描述
bool	bool	True if deletion was successful.

引发：

类型	描述
Exception	If the deletion operation fails.

get_collection_info

get_collection_info()

Get information about the collection.

返回：

类型	描述
dict[str, Any]	dict[str, Any]: Collection information including vectors count.

引发：

类型	描述
Exception	If the operation fails.

count_vectors

count_vectors(
    *,
    filter_conditions=None,
    include_read_collections=False,
)

Count vectors in the collection, optionally filtered.

参数：

名称	类型	描述	默认
filter_conditions	Optional[dict[str, Any]]	Filter conditions.	None
include_read_collections	bool	Whether to sum counts across configured fallback read collections in addition to the primary collection.	False

返回：

名称	类型	描述
int	int	Number of vectors matching the filter.

引发：

类型	描述
Exception	If the operation fails.