数据库与存储 API 参考

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

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

总览

数据层 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

Database models for Project Chameleon session storage.

This module defines the ORM models for: - Session management (conversations) - Message storage - Agent configuration - Knowledge source management - Agent-knowledge mounting relationships - MCP server registry and mounts - MCP credentials and call audits - Document chunks for RAG retrieval

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.
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.
created_at	datetime	When the message was created.

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.
created_at	datetime	When the agent was created.
updated_at	datetime	When the agent was last updated.

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

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.

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)

List recent sessions ordered by update time.

参数：

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

返回：

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

引发：

类型	描述
SQLAlchemyError	If the query fails.

create_message_record

create_message_record(
    db_session, *, session_id, role, content
)

Create a message row.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
session_id	str	Owning session id.	必需
role	str	Message role.	必需
content	str	Message content.	必需

返回：

名称	类型	描述
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.

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_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,
    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
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=None,
    description=None,
    status=None,
    system_prompt=None,
    model_name=None,
    model_provider=None,
    model_temperature=None,
)

Update an agent's fields.

参数：

名称	类型	描述	默认
db_session	Session	Active SQLAlchemy session.	必需
agent_record	Agent	Agent 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
system_prompt	Optional[str]	New system prompt, if provided.	None
model_name	Optional[str]	New model name, if provided.	None
model_provider	Optional[str]	New model provider, if provided.	None
model_temperature	Optional[float]	New model temperature, if provided.	None

返回：

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

引发：

类型	描述
SQLAlchemyError	If the database commit fails.

create_knowledge_source_record

create_knowledge_source_record(
    db_session,
    *,
    name,
    description=None,
    storage_type=StorageType.MINIO.value,
    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_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)

List knowledge sources ordered by creation time.

参数：

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

返回：

类型	描述
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,
)

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

返回：

名称	类型	描述
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, *, agent_id, source_id
)

Unmount a knowledge source from an agent.

参数：

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

返回：

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

引发：

类型	描述
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.

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,
    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.	必需
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=None,
    is_active=None,
    priority=None,
    allowed_tools_json=None,
    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]	Bound credential identifier.	None
is_active	Optional[bool]	Active flag.	None
priority	Optional[int]	Priority value.	None
allowed_tools_json	Optional[str]	Tool allowlist JSON.	None
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,
    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.	必需
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.

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.

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

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)

Delete vectors matching the filter conditions.

参数：

名称	类型	描述	默认
filter_conditions	dict[str, Any]	Filter conditions for deletion.	必需

返回：

名称	类型	描述
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)

Count vectors in the collection, optionally filtered.

参数：

名称	类型	描述	默认
filter_conditions	Optional[dict[str, Any]]	Filter conditions.	None

返回：

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

引发：

类型	描述
Exception	If the operation fails.