Files

moranzhi ba9b925c32 完成世界书、骰子、apiconfig页面处理

2026-04-30 01:35:10 +08:00

5.6 KiB

Raw Permalink Blame History

Backend Models 数据模型说明

目录结构

models/
├── __init__.py          # 包初始化,导出所有模型
├── sillytavern.py       # SillyTavern 兼容模型 (仅用于导入/导出)
├── internal.py          # 内部业务模型 (项目核心使用)
└── README.md            # 本文件

模型分类

1. SillyTavern 兼容模型 (`sillytavern.py`)

用途: 仅用于与 SillyTavern 格式的数据进行导入/导出兼容

特点:

严格遵循 SillyTavern 官方规范
不参与内部业务逻辑
所有字段名、结构与 SillyTavern 保持一致
前缀 ST 表示 SillyTavern

主要模型:

STWorldInfo - SillyTavern 世界书
STCharacterCard - SillyTavern 角色卡
STChatHeader / STChatMessage - SillyTavern 聊天记录
STGenerationPreset - SillyTavern 采样预设
STPromptPreset - SillyTavern 提示词预设

使用场景:

# 从 SillyTavern 导入时
st_data = json.load(file)
st_character = STCharacterCard(**st_data)

# 转换为内部模型
internal_character = converter.st_to_internal(st_character)

# 导出到 SillyTavern 时
st_data = converter.internal_to_st(internal_character)
json.dump(st_data.dict(), file)

2. 内部业务模型 (`internal.py`)

用途: 项目内部真正使用的数据结构,所有业务逻辑都基于这些模型

特点:

继承并扩展了 SillyTavern 的功能
添加了项目特色功能 (如 LOGIC 激活、RAG 配置、outputSchema 等)
所有 API 响应、数据存储、工作流交换都使用这些模型
无前缀,直接使用语义化名称

主要模型:

世界书相关

ActivationType - 激活方式枚举 (PERMANENT/KEYWORD/RAG/LOGIC)
LogicExpression - 逻辑表达式
RAGConfig - RAG 检索配置
WorldInfoEntry - 世界书条目
WorldInfo - 世界书

角色卡相关

OutputSchemaField - 结构化输出 schema
CharacterCard - 角色卡

聊天记录相关

ChatHeader - 聊天头
ChatMessage - 聊天消息
ChatLog - 完整聊天记录

预设相关

GenerationPreset - 采样参数预设
PromptRole - Prompt 角色枚举
PromptEntry - Prompt 条目
PromptPresetView - Prompt 预设视图

RAG 配置

RAGSearchConfig - RAG 搜索配置
CharacterRAGConfig - 角色卡 RAG 配置
ChatRAGConfig - 聊天 RAG 配置

使用场景:

# 业务逻辑中直接使用
from models import CharacterCard, WorldInfo

character = CharacterCard(
    id="uuid-123",
    name="Alice",
    description="...",
    ...
)

# API 响应
@app.get("/characters/{id}")
async def get_character(id: str):
    character = service.get_character(id)
    return character  # 返回 internal 模型

数据转换流程

SillyTavern 文件
    ↓ (导入)
STCharacterCard (sillytavern.py)
    ↓ (转换器)
CharacterCard (internal.py)
    ↓ (业务处理)
CharacterCard (internal.py)
    ↓ (转换器)
STCharacterCard (sillytavern.py)
    ↓ (导出)
SillyTavern 文件

开发规范

✅ 正确做法

业务逻辑使用 internal 模型

from models import CharacterCard

def create_character(data: dict) -> CharacterCard:
    return CharacterCard(**data)

导入时使用转换器

from models import STCharacterCard, CharacterCard
from models.converters import CharacterConverter

def import_character(file_path: str) -> CharacterCard:
    st_data = load_json(file_path)
    st_char = STCharacterCard(**st_data)
    return CharacterConverter.st_to_internal(st_char)

API 响应使用 internal 模型

@app.get("/characters")
async def list_characters() -> List[CharacterCard]:
    return service.list_characters()

❌ 错误做法

不要在业务逻辑中直接使用 ST 模型

# 错误!
from models import STCharacterCard

def process_character(char: STCharacterCard):
    ...

不要混合使用两种模型

# 错误!
character = CharacterCard(...)
character.name = st_character.data.name  # 不要混用

不要在 API 中暴露 ST 模型

# 错误!
@app.get("/characters")
async def list_characters() -> List[STCharacterCard]:
    ...

添加新模型

当需要添加新的数据类型时:

判断用途:
- 如果是为了 SillyTavern 兼容 → 添加到 sillytavern.py
- 如果是项目内部使用 → 添加到 internal.py
遵循命名规范:
- SillyTavern 模型: 前缀 ST
- 内部模型: 无前缀,使用清晰的语义化名称

添加详细注释:

class MyModel(BaseModel):
    """
    模型用途说明

    详细描述该模型的作用、使用场景等
    """
    field1: str = Field(..., description="字段说明")

在 __init__.py 中导出:

from .internal import MyModel

__all__ = [
    ...,
    'MyModel',
]

转换器 (待实现)

models/converters.py 将提供双向转换功能:

class CharacterConverter:
    @staticmethod
    def st_to_internal(st_char: STCharacterCard) -> CharacterCard:
        """SillyTavern → Internal"""
        ...
    
    @staticmethod
    def internal_to_st(int_char: CharacterCard) -> STCharacterCard:
        """Internal → SillyTavern"""
        ...

总结

sillytavern.py = 外部兼容层 (Import/Export Only)
internal.py = 内部业务层 (Core Business Logic)
永远在业务逻辑中使用 internal 模型
通过转换器进行格式转换

5.6 KiB Raw Permalink Blame History