refactor: port api/controllers/console/app/annotation.py api/controllers/console/explore/trial.py api/controllers/console/workspace/account.py api/controllers/console/workspace/members.py api/controllers/service_api/app/annotation.py to basemodel (#31833)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2026-02-03 10:59:00 +09:00 · 2026-02-03 10:59:00 +09:00 · 47f8de3f8e
parent 491fa9923b
commit 47f8de3f8e
12 changed files with 307 additions and 204 deletions
--- a/api/controllers/console/app/annotation.py
+++ b/api/controllers/console/app/annotation.py
@ -1,10 +1,11 @@
 from typing import Any, Literal

 from flask import abort, make_response, request
-from flask_restx import Resource, fields, marshal, marshal_with
-from pydantic import BaseModel, Field, field_validator
+from flask_restx import Resource
+from pydantic import BaseModel, Field, TypeAdapter, field_validator

 from controllers.common.errors import NoFileUploadedError, TooManyFilesError
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import (
    account_initialization_required,
@ -16,9 +17,11 @@ from controllers.console.wraps import (
 )
 from extensions.ext_redis import redis_client
 from fields.annotation_fields import (
-    annotation_fields,
-    annotation_hit_history_fields,
-    build_annotation_model,
+    Annotation,
+    AnnotationExportList,
+    AnnotationHitHistory,
+    AnnotationHitHistoryList,
+    AnnotationList,
 )
 from libs.helper import uuid_value
 from libs.login import login_required
@ -89,6 +92,14 @@ reg(CreateAnnotationPayload)
 reg(UpdateAnnotationPayload)
 reg(AnnotationReplyStatusQuery)
 reg(AnnotationFilePayload)
+register_schema_models(
+    console_ns,
+    Annotation,
+    AnnotationList,
+    AnnotationExportList,
+    AnnotationHitHistory,
+    AnnotationHitHistoryList,
+)


@console_ns.route("/apps/<uuid:app_id>/annotation-reply/<string:action>")
@ -202,33 +213,33 @@ class AnnotationApi(Resource):

        app_id = str(app_id)
        annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(app_id, page, limit, keyword)
-        response = {
-            "data": marshal(annotation_list, annotation_fields),
-            "has_more": len(annotation_list) == limit,
-            "limit": limit,
-            "total": total,
-            "page": page,
-        }
-        return response, 200
+        annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
+        response = AnnotationList(
+            data=annotation_models,
+            has_more=len(annotation_list) == limit,
+            limit=limit,
+            total=total,
+            page=page,
+        )
+        return response.model_dump(mode="json"), 200

    @console_ns.doc("create_annotation")
    @console_ns.doc(description="Create a new annotation for an app")
    @console_ns.doc(params={"app_id": "Application ID"})
    @console_ns.expect(console_ns.models[CreateAnnotationPayload.__name__])
-    @console_ns.response(201, "Annotation created successfully", build_annotation_model(console_ns))
+    @console_ns.response(201, "Annotation created successfully", console_ns.models[Annotation.__name__])
    @console_ns.response(403, "Insufficient permissions")
    @setup_required
    @login_required
    @account_initialization_required
    @cloud_edition_billing_resource_check("annotation")
-    @marshal_with(annotation_fields)
    @edit_permission_required
    def post(self, app_id):
        app_id = str(app_id)
        args = CreateAnnotationPayload.model_validate(console_ns.payload)
        data = args.model_dump(exclude_none=True)
        annotation = AppAnnotationService.up_insert_app_annotation_from_message(data, app_id)
-        return annotation
+        return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")

    @setup_required
    @login_required
@ -265,7 +276,7 @@ class AnnotationExportApi(Resource):
    @console_ns.response(
        200,
        "Annotations exported successfully",
-        console_ns.model("AnnotationList", {"data": fields.List(fields.Nested(build_annotation_model(console_ns)))}),
+        console_ns.models[AnnotationExportList.__name__],
    )
    @console_ns.response(403, "Insufficient permissions")
    @setup_required
@ -275,7 +286,8 @@ class AnnotationExportApi(Resource):
    def get(self, app_id):
        app_id = str(app_id)
        annotation_list = AppAnnotationService.export_annotation_list_by_app_id(app_id)
-        response_data = {"data": marshal(annotation_list, annotation_fields)}
+        annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
+        response_data = AnnotationExportList(data=annotation_models).model_dump(mode="json")

        # Create response with secure headers for CSV export
        response = make_response(response_data, 200)
@ -290,7 +302,7 @@ class AnnotationUpdateDeleteApi(Resource):
    @console_ns.doc("update_delete_annotation")
    @console_ns.doc(description="Update or delete an annotation")
    @console_ns.doc(params={"app_id": "Application ID", "annotation_id": "Annotation ID"})
-    @console_ns.response(200, "Annotation updated successfully", build_annotation_model(console_ns))
+    @console_ns.response(200, "Annotation updated successfully", console_ns.models[Annotation.__name__])
    @console_ns.response(204, "Annotation deleted successfully")
    @console_ns.response(403, "Insufficient permissions")
    @console_ns.expect(console_ns.models[UpdateAnnotationPayload.__name__])
@ -299,7 +311,6 @@ class AnnotationUpdateDeleteApi(Resource):
    @account_initialization_required
    @cloud_edition_billing_resource_check("annotation")
    @edit_permission_required
-    @marshal_with(annotation_fields)
    def post(self, app_id, annotation_id):
        app_id = str(app_id)
        annotation_id = str(annotation_id)
@ -307,7 +318,7 @@ class AnnotationUpdateDeleteApi(Resource):
        annotation = AppAnnotationService.update_app_annotation_directly(
            args.model_dump(exclude_none=True), app_id, annotation_id
        )
-        return annotation
+        return Annotation.model_validate(annotation, from_attributes=True).model_dump(mode="json")

    @setup_required
    @login_required
@ -415,14 +426,7 @@ class AnnotationHitHistoryListApi(Resource):
    @console_ns.response(
        200,
        "Hit histories retrieved successfully",
-        console_ns.model(
-            "AnnotationHitHistoryList",
-            {
-                "data": fields.List(
-                    fields.Nested(console_ns.model("AnnotationHitHistoryItem", annotation_hit_history_fields))
-                )
-            },
-        ),
+        console_ns.models[AnnotationHitHistoryList.__name__],
    )
    @console_ns.response(403, "Insufficient permissions")
    @setup_required
@ -437,11 +441,14 @@ class AnnotationHitHistoryListApi(Resource):
        annotation_hit_history_list, total = AppAnnotationService.get_annotation_hit_histories(
            app_id, annotation_id, page, limit
        )
-        response = {
-            "data": marshal(annotation_hit_history_list, annotation_hit_history_fields),
-            "has_more": len(annotation_hit_history_list) == limit,
-            "limit": limit,
-            "total": total,
-            "page": page,
-        }
-        return response
+        history_models = TypeAdapter(list[AnnotationHitHistory]).validate_python(
+            annotation_hit_history_list, from_attributes=True
+        )
+        response = AnnotationHitHistoryList(
+            data=history_models,
+            has_more=len(annotation_hit_history_list) == limit,
+            limit=limit,
+            total=total,
+            page=page,
+        )
+        return response.model_dump(mode="json")
--- a/api/controllers/console/explore/trial.py
+++ b/api/controllers/console/explore/trial.py
@ -9,7 +9,7 @@ import services
 from controllers.common.fields import Parameters as ParametersResponse
 from controllers.common.fields import Site as SiteResponse
 from controllers.common.schema import get_or_create_model
-from controllers.console import api, console_ns
+from controllers.console import api
 from controllers.console.app.error import (
    AppUnavailableError,
    AudioTooLargeError,
@ -51,7 +51,7 @@ from fields.app_fields import (
    tag_fields,
 )
 from fields.dataset_fields import dataset_fields
-from fields.member_fields import build_simple_account_model
+from fields.member_fields import simple_account_fields
 from fields.workflow_fields import (
    conversation_variable_fields,
    pipeline_variable_fields,
@ -103,7 +103,7 @@ app_detail_fields_with_site_copy["tags"] = fields.List(fields.Nested(tag_model))
 app_detail_fields_with_site_copy["site"] = fields.Nested(site_model)
 app_detail_with_site_model = get_or_create_model("TrialAppDetailWithSite", app_detail_fields_with_site_copy)

-simple_account_model = build_simple_account_model(console_ns)
+simple_account_model = get_or_create_model("SimpleAccount", simple_account_fields)
 conversation_variable_model = get_or_create_model("TrialConversationVariable", conversation_variable_fields)
 pipeline_variable_model = get_or_create_model("TrialPipelineVariable", pipeline_variable_fields)

--- a/api/controllers/console/workspace/account.py
+++ b/api/controllers/console/workspace/account.py
@ -12,6 +12,7 @@ from sqlalchemy.orm import Session

 from configs import dify_config
 from constants.languages import supported_language
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.auth.error import (
    EmailAlreadyInUseError,
@ -37,7 +38,7 @@ from controllers.console.wraps import (
    setup_required,
 )
 from extensions.ext_database import db
-from fields.member_fields import account_fields
+from fields.member_fields import Account as AccountResponse
 from libs.datetime_utils import naive_utc_now
 from libs.helper import EmailStr, TimestampField, extract_remote_ip, timezone
 from libs.login import current_account_with_tenant, login_required
@ -170,6 +171,12 @@ reg(ChangeEmailSendPayload)
 reg(ChangeEmailValidityPayload)
 reg(ChangeEmailResetPayload)
 reg(CheckEmailUniquePayload)
+register_schema_models(console_ns, AccountResponse)
+
+
+def _serialize_account(account) -> dict:
+    return AccountResponse.model_validate(account, from_attributes=True).model_dump(mode="json")
+

 integrate_fields = {
    "provider": fields.String,
@ -236,11 +243,11 @@ class AccountProfileApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    @enterprise_license_required
    def get(self):
        current_user, _ = current_account_with_tenant()
-        return current_user
+        return _serialize_account(current_user)


@console_ns.route("/account/name")
@ -249,14 +256,14 @@ class AccountNameApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
        args = AccountNamePayload.model_validate(payload)
        updated_account = AccountService.update_account(current_user, name=args.name)

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/avatar")
@ -265,7 +272,7 @@ class AccountAvatarApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
@ -273,7 +280,7 @@ class AccountAvatarApi(Resource):

        updated_account = AccountService.update_account(current_user, avatar=args.avatar)

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/interface-language")
@ -282,7 +289,7 @@ class AccountInterfaceLanguageApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
@ -290,7 +297,7 @@ class AccountInterfaceLanguageApi(Resource):

        updated_account = AccountService.update_account(current_user, interface_language=args.interface_language)

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/interface-theme")
@ -299,7 +306,7 @@ class AccountInterfaceThemeApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
@ -307,7 +314,7 @@ class AccountInterfaceThemeApi(Resource):

        updated_account = AccountService.update_account(current_user, interface_theme=args.interface_theme)

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/timezone")
@ -316,7 +323,7 @@ class AccountTimezoneApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
@ -324,7 +331,7 @@ class AccountTimezoneApi(Resource):

        updated_account = AccountService.update_account(current_user, timezone=args.timezone)

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/password")
@ -333,7 +340,7 @@ class AccountPasswordApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        current_user, _ = current_account_with_tenant()
        payload = console_ns.payload or {}
@ -344,7 +351,7 @@ class AccountPasswordApi(Resource):
        except ServiceCurrentPasswordIncorrectError:
            raise CurrentPasswordIncorrectError()

-        return {"result": "success"}
+        return _serialize_account(current_user)


@console_ns.route("/account/integrates")
@ -620,7 +627,7 @@ class ChangeEmailResetApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_fields)
+    @console_ns.response(200, "Success", console_ns.models[AccountResponse.__name__])
    def post(self):
        payload = console_ns.payload or {}
        args = ChangeEmailResetPayload.model_validate(payload)
@ -649,7 +656,7 @@ class ChangeEmailResetApi(Resource):
            email=normalized_new_email,
        )

-        return updated_account
+        return _serialize_account(updated_account)


@console_ns.route("/account/change-email/check-email-unique")
--- a/api/controllers/console/workspace/members.py
+++ b/api/controllers/console/workspace/members.py
@ -1,12 +1,12 @@
 from urllib import parse

 from flask import abort, request
-from flask_restx import Resource, fields, marshal_with
-from pydantic import BaseModel, Field
+from flask_restx import Resource
+from pydantic import BaseModel, Field, TypeAdapter

 import services
 from configs import dify_config
-from controllers.common.schema import get_or_create_model, register_enum_models
+from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.auth.error import (
    CannotTransferOwnerToSelfError,
@ -25,7 +25,7 @@ from controllers.console.wraps import (
    setup_required,
 )
 from extensions.ext_database import db
-from fields.member_fields import account_with_role_fields, account_with_role_list_fields
+from fields.member_fields import AccountWithRole, AccountWithRoleList
 from libs.helper import extract_remote_ip
 from libs.login import current_account_with_tenant, login_required
 from models.account import Account, TenantAccountRole
@ -69,12 +69,7 @@ reg(OwnerTransferEmailPayload)
 reg(OwnerTransferCheckPayload)
 reg(OwnerTransferPayload)
 register_enum_models(console_ns, TenantAccountRole)
-
-account_with_role_model = get_or_create_model("AccountWithRole", account_with_role_fields)
-
-account_with_role_list_fields_copy = account_with_role_list_fields.copy()
-account_with_role_list_fields_copy["accounts"] = fields.List(fields.Nested(account_with_role_model))
-account_with_role_list_model = get_or_create_model("AccountWithRoleList", account_with_role_list_fields_copy)
+register_schema_models(console_ns, AccountWithRole, AccountWithRoleList)


@console_ns.route("/workspaces/current/members")
@ -84,13 +79,15 @@ class MemberListApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_with_role_list_model)
+    @console_ns.response(200, "Success", console_ns.models[AccountWithRoleList.__name__])
    def get(self):
        current_user, _ = current_account_with_tenant()
        if not current_user.current_tenant:
            raise ValueError("No current tenant")
        members = TenantService.get_tenant_members(current_user.current_tenant)
-        return {"result": "success", "accounts": members}, 200
+        member_models = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
+        response = AccountWithRoleList(accounts=member_models)
+        return response.model_dump(mode="json"), 200


@console_ns.route("/workspaces/current/members/invite-email")
@ -235,13 +232,15 @@ class DatasetOperatorMemberListApi(Resource):
    @setup_required
    @login_required
    @account_initialization_required
-    @marshal_with(account_with_role_list_model)
+    @console_ns.response(200, "Success", console_ns.models[AccountWithRoleList.__name__])
    def get(self):
        current_user, _ = current_account_with_tenant()
        if not current_user.current_tenant:
            raise ValueError("No current tenant")
        members = TenantService.get_dataset_operator_members(current_user.current_tenant)
-        return {"result": "success", "accounts": members}, 200
+        member_models = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
+        response = AccountWithRoleList(accounts=member_models)
+        return response.model_dump(mode="json"), 200


@console_ns.route("/workspaces/current/members/send-owner-transfer-confirm-email")
--- a/api/controllers/service_api/app/annotation.py
+++ b/api/controllers/service_api/app/annotation.py
@ -1,16 +1,16 @@
 from typing import Literal

 from flask import request
-from flask_restx import Namespace, Resource, fields
+from flask_restx import Resource
 from flask_restx.api import HTTPStatus
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, TypeAdapter

 from controllers.common.schema import register_schema_models
 from controllers.console.wraps import edit_permission_required
 from controllers.service_api import service_api_ns
 from controllers.service_api.wraps import validate_app_token
 from extensions.ext_redis import redis_client
-from fields.annotation_fields import annotation_fields, build_annotation_model
+from fields.annotation_fields import Annotation, AnnotationList
 from models.model import App
 from services.annotation_service import AppAnnotationService

@ -26,7 +26,9 @@ class AnnotationReplyActionPayload(BaseModel):
    embedding_model_name: str = Field(description="Embedding model name")


-register_schema_models(service_api_ns, AnnotationCreatePayload, AnnotationReplyActionPayload)
+register_schema_models(
+    service_api_ns, AnnotationCreatePayload, AnnotationReplyActionPayload, Annotation, AnnotationList
+)


@service_api_ns.route("/apps/annotation-reply/<string:action>")
@ -83,23 +85,6 @@ class AnnotationReplyActionStatusApi(Resource):
        return {"job_id": job_id, "job_status": job_status, "error_msg": error_msg}, 200


-# Define annotation list response model
-annotation_list_fields = {
-    "data": fields.List(fields.Nested(annotation_fields)),
-    "has_more": fields.Boolean,
-    "limit": fields.Integer,
-    "total": fields.Integer,
-    "page": fields.Integer,
-}
-
-
-def build_annotation_list_model(api_or_ns: Namespace):
-    """Build the annotation list model for the API or Namespace."""
-    copied_annotation_list_fields = annotation_list_fields.copy()
-    copied_annotation_list_fields["data"] = fields.List(fields.Nested(build_annotation_model(api_or_ns)))
-    return api_or_ns.model("AnnotationList", copied_annotation_list_fields)
-
-
@service_api_ns.route("/apps/annotations")
 class AnnotationListApi(Resource):
    @service_api_ns.doc("list_annotations")
@ -110,8 +95,12 @@ class AnnotationListApi(Resource):
            401: "Unauthorized - invalid API token",
        }
    )
+    @service_api_ns.response(
+        200,
+        "Annotations retrieved successfully",
+        service_api_ns.models[AnnotationList.__name__],
+    )
    @validate_app_token
-    @service_api_ns.marshal_with(build_annotation_list_model(service_api_ns))
    def get(self, app_model: App):
        """List annotations for the application."""
        page = request.args.get("page", default=1, type=int)
@ -119,13 +108,15 @@ class AnnotationListApi(Resource):
        keyword = request.args.get("keyword", default="", type=str)

        annotation_list, total = AppAnnotationService.get_annotation_list_by_app_id(app_model.id, page, limit, keyword)
-        return {
-            "data": annotation_list,
-            "has_more": len(annotation_list) == limit,
-            "limit": limit,
-            "total": total,
-            "page": page,
-        }
+        annotation_models = TypeAdapter(list[Annotation]).validate_python(annotation_list, from_attributes=True)
+        response = AnnotationList(
+            data=annotation_models,
+            has_more=len(annotation_list) == limit,
+            limit=limit,
+            total=total,
+            page=page,
+        )
+        return response.model_dump(mode="json")

    @service_api_ns.expect(service_api_ns.models[AnnotationCreatePayload.__name__])
    @service_api_ns.doc("create_annotation")
@ -136,13 +127,18 @@ class AnnotationListApi(Resource):
            401: "Unauthorized - invalid API token",
        }
    )
+    @service_api_ns.response(
+        HTTPStatus.CREATED,
+        "Annotation created successfully",
+        service_api_ns.models[Annotation.__name__],
+    )
    @validate_app_token
-    @service_api_ns.marshal_with(build_annotation_model(service_api_ns), code=HTTPStatus.CREATED)
    def post(self, app_model: App):
        """Create a new annotation."""
        args = AnnotationCreatePayload.model_validate(service_api_ns.payload or {}).model_dump()
        annotation = AppAnnotationService.insert_app_annotation_directly(args, app_model.id)
-        return annotation, 201
+        response = Annotation.model_validate(annotation, from_attributes=True)
+        return response.model_dump(mode="json"), HTTPStatus.CREATED


@service_api_ns.route("/apps/annotations/<uuid:annotation_id>")
@ -159,14 +155,19 @@ class AnnotationUpdateDeleteApi(Resource):
            404: "Annotation not found",
        }
    )
+    @service_api_ns.response(
+        200,
+        "Annotation updated successfully",
+        service_api_ns.models[Annotation.__name__],
+    )
    @validate_app_token
    @edit_permission_required
-    @service_api_ns.marshal_with(build_annotation_model(service_api_ns))
    def put(self, app_model: App, annotation_id: str):
        """Update an existing annotation."""
        args = AnnotationCreatePayload.model_validate(service_api_ns.payload or {}).model_dump()
        annotation = AppAnnotationService.update_app_annotation_directly(args, app_model.id, annotation_id)
-        return annotation
+        response = Annotation.model_validate(annotation, from_attributes=True)
+        return response.model_dump(mode="json")

    @service_api_ns.doc("delete_annotation")
    @service_api_ns.doc(description="Delete an annotation")
--- a/api/controllers/service_api/dataset/dataset.py
+++ b/api/controllers/service_api/dataset/dataset.py
@ -17,7 +17,7 @@ from controllers.service_api.wraps import (
 from core.model_runtime.entities.model_entities import ModelType
 from core.provider_manager import ProviderManager
 from fields.dataset_fields import dataset_detail_fields
-from fields.tag_fields import build_dataset_tag_fields
+from fields.tag_fields import DataSetTag
 from libs.login import current_user
 from models.account import Account
 from models.dataset import DatasetPermissionEnum
@ -114,6 +114,7 @@ register_schema_models(
    TagBindingPayload,
    TagUnbindingPayload,
    DatasetListQuery,
+    DataSetTag,
 )


@ -480,15 +481,14 @@ class DatasetTagsApi(DatasetApiResource):
            401: "Unauthorized - invalid API token",
        }
    )
-    @service_api_ns.marshal_with(build_dataset_tag_fields(service_api_ns))
    def get(self, _):
        """Get all knowledge type tags."""
        assert isinstance(current_user, Account)
        cid = current_user.current_tenant_id
        assert cid is not None
        tags = TagService.get_tags("knowledge", cid)
-
-        return tags, 200
+        tag_models = TypeAdapter(list[DataSetTag]).validate_python(tags, from_attributes=True)
+        return [tag.model_dump(mode="json") for tag in tag_models], 200

    @service_api_ns.expect(service_api_ns.models[TagCreatePayload.__name__])
    @service_api_ns.doc("create_dataset_tag")
@ -500,7 +500,6 @@ class DatasetTagsApi(DatasetApiResource):
            403: "Forbidden - insufficient permissions",
        }
    )
-    @service_api_ns.marshal_with(build_dataset_tag_fields(service_api_ns))
    def post(self, _):
        """Add a knowledge type tag."""
        assert isinstance(current_user, Account)
@ -510,7 +509,9 @@ class DatasetTagsApi(DatasetApiResource):
        payload = TagCreatePayload.model_validate(service_api_ns.payload or {})
        tag = TagService.save_tags({"name": payload.name, "type": "knowledge"})

-        response = {"id": tag.id, "name": tag.name, "type": tag.type, "binding_count": 0}
+        response = DataSetTag.model_validate(
+            {"id": tag.id, "name": tag.name, "type": tag.type, "binding_count": 0}
+        ).model_dump(mode="json")
        return response, 200

    @service_api_ns.expect(service_api_ns.models[TagUpdatePayload.__name__])
@ -523,7 +524,6 @@ class DatasetTagsApi(DatasetApiResource):
            403: "Forbidden - insufficient permissions",
        }
    )
-    @service_api_ns.marshal_with(build_dataset_tag_fields(service_api_ns))
    def patch(self, _):
        assert isinstance(current_user, Account)
        if not (current_user.has_edit_permission or current_user.is_dataset_editor):
@ -536,8 +536,9 @@ class DatasetTagsApi(DatasetApiResource):

        binding_count = TagService.get_tag_binding_count(tag_id)

-        response = {"id": tag.id, "name": tag.name, "type": tag.type, "binding_count": binding_count}
-
+        response = DataSetTag.model_validate(
+            {"id": tag.id, "name": tag.name, "type": tag.type, "binding_count": binding_count}
+        ).model_dump(mode="json")
        return response, 200

    @service_api_ns.expect(service_api_ns.models[TagDeletePayload.__name__])
--- a/api/fields/annotation_fields.py
+++ b/api/fields/annotation_fields.py
@ -1,36 +1,69 @@
-from flask_restx import Namespace, fields
+from __future__ import annotations

-from libs.helper import TimestampField
+from datetime import datetime

-annotation_fields = {
-    "id": fields.String,
-    "question": fields.String,
-    "answer": fields.Raw(attribute="content"),
-    "hit_count": fields.Integer,
-    "created_at": TimestampField,
-    # 'account': fields.Nested(simple_account_fields, allow_null=True)
-}
+from pydantic import BaseModel, ConfigDict, Field, field_validator


-def build_annotation_model(api_or_ns: Namespace):
-    """Build the annotation model for the API or Namespace."""
-    return api_or_ns.model("Annotation", annotation_fields)
+def _to_timestamp(value: datetime | int | None) -> int | None:
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    return value


-annotation_list_fields = {
-    "data": fields.List(fields.Nested(annotation_fields)),
-}
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        extra="ignore",
+        populate_by_name=True,
+        serialize_by_alias=True,
+        protected_namespaces=(),
+    )

-annotation_hit_history_fields = {
-    "id": fields.String,
-    "source": fields.String,
-    "score": fields.Float,
-    "question": fields.String,
-    "created_at": TimestampField,
-    "match": fields.String(attribute="annotation_question"),
-    "response": fields.String(attribute="annotation_content"),
-}

-annotation_hit_history_list_fields = {
-    "data": fields.List(fields.Nested(annotation_hit_history_fields)),
-}
+class Annotation(ResponseModel):
+    id: str
+    question: str | None = None
+    answer: str | None = Field(default=None, validation_alias="content")
+    hit_count: int | None = None
+    created_at: int | None = None
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def _normalize_created_at(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+class AnnotationList(ResponseModel):
+    data: list[Annotation]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
+
+
+class AnnotationExportList(ResponseModel):
+    data: list[Annotation]
+
+
+class AnnotationHitHistory(ResponseModel):
+    id: str
+    source: str | None = None
+    score: float | None = None
+    question: str | None = None
+    created_at: int | None = None
+    match: str | None = Field(default=None, validation_alias="annotation_question")
+    response: str | None = Field(default=None, validation_alias="annotation_content")
+
+    @field_validator("created_at", mode="before")
+    @classmethod
+    def _normalize_created_at(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+class AnnotationHitHistoryList(ResponseModel):
+    data: list[AnnotationHitHistory]
+    has_more: bool
+    limit: int
+    total: int
+    page: int
--- a/api/fields/end_user_fields.py
+++ b/api/fields/end_user_fields.py
@ -1,4 +1,7 @@
-from flask_restx import Namespace, fields
+from __future__ import annotations
+
+from flask_restx import fields
+from pydantic import BaseModel, ConfigDict

 simple_end_user_fields = {
    "id": fields.String,
@ -8,5 +11,18 @@ simple_end_user_fields = {
 }


-def build_simple_end_user_model(api_or_ns: Namespace):
-    return api_or_ns.model("SimpleEndUser", simple_end_user_fields)
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        extra="ignore",
+        populate_by_name=True,
+        serialize_by_alias=True,
+        protected_namespaces=(),
+    )
+
+
+class SimpleEndUser(ResponseModel):
+    id: str
+    type: str
+    is_anonymous: bool
+    session_id: str | None = None
--- a/api/fields/member_fields.py
+++ b/api/fields/member_fields.py
@ -1,6 +1,11 @@
-from flask_restx import Namespace, fields
+from __future__ import annotations

-from libs.helper import AvatarUrlField, TimestampField
+from datetime import datetime
+
+from flask_restx import fields
+from pydantic import BaseModel, ConfigDict, computed_field, field_validator
+
+from core.file import helpers as file_helpers

 simple_account_fields = {
    "id": fields.String,
@ -9,36 +14,78 @@ simple_account_fields = {
 }


-def build_simple_account_model(api_or_ns: Namespace):
-    return api_or_ns.model("SimpleAccount", simple_account_fields)
+def _to_timestamp(value: datetime | int | None) -> int | None:
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    return value


-account_fields = {
-    "id": fields.String,
-    "name": fields.String,
-    "avatar": fields.String,
-    "avatar_url": AvatarUrlField,
-    "email": fields.String,
-    "is_password_set": fields.Boolean,
-    "interface_language": fields.String,
-    "interface_theme": fields.String,
-    "timezone": fields.String,
-    "last_login_at": TimestampField,
-    "last_login_ip": fields.String,
-    "created_at": TimestampField,
-}
+def _build_avatar_url(avatar: str | None) -> str | None:
+    if avatar is None:
+        return None
+    if avatar.startswith(("http://", "https://")):
+        return avatar
+    return file_helpers.get_signed_file_url(avatar)

-account_with_role_fields = {
-    "id": fields.String,
-    "name": fields.String,
-    "avatar": fields.String,
-    "avatar_url": AvatarUrlField,
-    "email": fields.String,
-    "last_login_at": TimestampField,
-    "last_active_at": TimestampField,
-    "created_at": TimestampField,
-    "role": fields.String,
-    "status": fields.String,
-}

-account_with_role_list_fields = {"accounts": fields.List(fields.Nested(account_with_role_fields))}
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        extra="ignore",
+        populate_by_name=True,
+        serialize_by_alias=True,
+        protected_namespaces=(),
+    )
+
+
+class SimpleAccount(ResponseModel):
+    id: str
+    name: str
+    email: str
+
+
+class _AccountAvatar(ResponseModel):
+    avatar: str | None = None
+
+    @computed_field(return_type=str | None)  # type: ignore[prop-decorator]
+    @property
+    def avatar_url(self) -> str | None:
+        return _build_avatar_url(self.avatar)
+
+
+class Account(_AccountAvatar):
+    id: str
+    name: str
+    email: str
+    is_password_set: bool
+    interface_language: str | None = None
+    interface_theme: str | None = None
+    timezone: str | None = None
+    last_login_at: int | None = None
+    last_login_ip: str | None = None
+    created_at: int | None = None
+
+    @field_validator("last_login_at", "created_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+class AccountWithRole(_AccountAvatar):
+    id: str
+    name: str
+    email: str
+    last_login_at: int | None = None
+    last_active_at: int | None = None
+    created_at: int | None = None
+    role: str
+    status: str
+
+    @field_validator("last_login_at", "last_active_at", "created_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
+        return _to_timestamp(value)
+
+
+class AccountWithRoleList(ResponseModel):
+    accounts: list[AccountWithRole]
--- a/api/fields/tag_fields.py
+++ b/api/fields/tag_fields.py
@ -1,12 +1,20 @@
-from flask_restx import Namespace, fields
+from __future__ import annotations

-dataset_tag_fields = {
-    "id": fields.String,
-    "name": fields.String,
-    "type": fields.String,
-    "binding_count": fields.String,
-}
+from pydantic import BaseModel, ConfigDict


-def build_dataset_tag_fields(api_or_ns: Namespace):
-    return api_or_ns.model("DataSetTag", dataset_tag_fields)
+class ResponseModel(BaseModel):
+    model_config = ConfigDict(
+        from_attributes=True,
+        extra="ignore",
+        populate_by_name=True,
+        serialize_by_alias=True,
+        protected_namespaces=(),
+    )
+
+
+class DataSetTag(ResponseModel):
+    id: str
+    name: str
+    type: str
+    binding_count: str | None = None
--- a/api/fields/workflow_app_log_fields.py
+++ b/api/fields/workflow_app_log_fields.py
@ -1,7 +1,7 @@
 from flask_restx import Namespace, fields

-from fields.end_user_fields import build_simple_end_user_model, simple_end_user_fields
-from fields.member_fields import build_simple_account_model, simple_account_fields
+from fields.end_user_fields import simple_end_user_fields
+from fields.member_fields import simple_account_fields
 from fields.workflow_run_fields import (
    build_workflow_run_for_archived_log_model,
    build_workflow_run_for_log_model,
@ -25,17 +25,9 @@ workflow_app_log_partial_fields = {
 def build_workflow_app_log_partial_model(api_or_ns: Namespace):
    """Build the workflow app log partial model for the API or Namespace."""
    workflow_run_model = build_workflow_run_for_log_model(api_or_ns)
-    simple_account_model = build_simple_account_model(api_or_ns)
-    simple_end_user_model = build_simple_end_user_model(api_or_ns)

    copied_fields = workflow_app_log_partial_fields.copy()
    copied_fields["workflow_run"] = fields.Nested(workflow_run_model, attribute="workflow_run", allow_null=True)
-    copied_fields["created_by_account"] = fields.Nested(
-        simple_account_model, attribute="created_by_account", allow_null=True
-    )
-    copied_fields["created_by_end_user"] = fields.Nested(
-        simple_end_user_model, attribute="created_by_end_user", allow_null=True
-    )
    return api_or_ns.model("WorkflowAppLogPartial", copied_fields)


@ -52,17 +44,9 @@ workflow_archived_log_partial_fields = {
 def build_workflow_archived_log_partial_model(api_or_ns: Namespace):
    """Build the workflow archived log partial model for the API or Namespace."""
    workflow_run_model = build_workflow_run_for_archived_log_model(api_or_ns)
-    simple_account_model = build_simple_account_model(api_or_ns)
-    simple_end_user_model = build_simple_end_user_model(api_or_ns)

    copied_fields = workflow_archived_log_partial_fields.copy()
    copied_fields["workflow_run"] = fields.Nested(workflow_run_model, allow_null=True)
-    copied_fields["created_by_account"] = fields.Nested(
-        simple_account_model, attribute="created_by_account", allow_null=True
-    )
-    copied_fields["created_by_end_user"] = fields.Nested(
-        simple_end_user_model, attribute="created_by_end_user", allow_null=True
-    )
    return api_or_ns.model("WorkflowArchivedLogPartial", copied_fields)


--- a/api/services/annotation_service.py
+++ b/api/services/annotation_service.py
@ -158,7 +158,7 @@ class AppAnnotationService:
                .order_by(MessageAnnotation.created_at.desc(), MessageAnnotation.id.desc())
            )
        annotations = db.paginate(select=stmt, page=page, per_page=limit, max_per_page=100, error_out=False)
-        return annotations.items, annotations.total
+        return annotations.items, annotations.total or 0

    @classmethod
    def export_annotation_list_by_app_id(cls, app_id: str):
@ -524,7 +524,7 @@ class AppAnnotationService:
        annotation_hit_histories = db.paginate(
            select=stmt, page=page, per_page=limit, max_per_page=100, error_out=False
        )
-        return annotation_hit_histories.items, annotation_hit_histories.total
+        return annotation_hit_histories.items, annotation_hit_histories.total or 0

    @classmethod
    def get_annotation_by_id(cls, annotation_id: str) -> MessageAnnotation | None: