Add model management to RAGFlow HTTP API #6

as-ondewo · 2026-01-02T21:53:03Z

No description provided.

…d support for individual models and added tests for the add_model API.

… required fields across various factories. Added extensive test cases to ensure proper error handling for missing parameters.

…e hints

as-ondewo · 2026-01-13T17:34:59Z

api/utils/validation_utils.py

+        - Factory-level: requires llm_factory and api_key (or special auth fields)
+        - Individual model: requires llm_factory, llm_name, model_type, and api_base (for local models) or api_key
+        """
+        from common.constants import LLMType


only use module level imports

as-ondewo · 2026-01-14T00:00:18Z

api/utils/validation_utils.py

+                raise PydanticCustomError("field_required", "model_type is required when adding an individual model")
+
+            # Validate model_type
+            valid_types = [LLMType.CHAT, LLMType.EMBEDDING, LLMType.RERANK, LLMType.IMAGE2TEXT, LLMType.SPEECH2TEXT, LLMType.TTS, LLMType.OCR]


List is unnecessary. To check if model type is valid use self.model_type in LLMType. To get list of LLMTypes use [t.value for t in LLMType]

as-ondewo · 2026-01-14T01:00:48Z

api/utils/validation_utils.py

+                        raise PydanticCustomError("field_required", "spark_app_id, spark_api_secret, and spark_api_key are required for XunFei Spark TTS models")
+
+        # Factory-level addition mode
+        else:


When adding all models of a factory only check factories for which this is actually supported. For all other's check that the API key is provided

as-ondewo · 2026-01-14T01:24:14Z

api/utils/validation_utils.py

+
+            # For local models, api_base is typically required
+            if is_local and not self.api_base and not self.api_key:
+                raise PydanticCustomError("field_required", "api_base is required for local/self-hosted models when api_key is not provided")


For local models the base URL should always be required even if an API key is provided

as-ondewo · 2026-01-14T01:27:43Z

api/utils/validation_utils.py

+            if is_local and not self.api_base and not self.api_key:
+                raise PydanticCustomError("field_required", "api_base is required for local/self-hosted models when api_key is not provided")
+
+            # For individual model mode, validate factory-specific required parameters


use match-case construct

as-ondewo · 2026-01-14T01:28:50Z

api/utils/validation_utils.py

+            # For individual model mode, validate factory-specific required parameters
+            if self.llm_factory == "VolcEngine":
+                if not self.ark_api_key or not self.endpoint_id:
+                    raise PydanticCustomError("field_required", "ark_api_key and endpoint_id are required for VolcEngine individual model addition")


create helper function for these checks to reduce code duplication

should also check that the fields don't just contain whitespace

as-ondewo · 2026-01-14T01:31:42Z

api/utils/validation_utils.py

+                )
+                if not self.api_key and not has_special_auth:
+                    raise PydanticCustomError("field_required", "api_key or appropriate authentication fields are required for factory-level addition")
+            # For local factories, empty api_key is allowed in factory-level mode (validation skipped above)


This comment is misleading. Local models aren't supported for factory-level adding

as-ondewo · 2026-01-14T01:49:22Z

api/apps/sdk/users.py

+
+@manager.route("/models", methods=["POST"])  # noqa: F821
+@token_required
+async def add_model(tenant_id: str) -> Response:


This function is full of duplicate validations that is already handled by the Pydantic request validator. Please rework it to remove the redundant code.

as-ondewo · 2026-01-14T11:48:10Z

test/testcases/test_http_api/test_user_models_management/conftest.py

+
+@pytest.fixture(scope="class")
+def cleanup_added_models(request: FixtureRequest, HttpApiAuth):
+    """Fixture to clean up models added during tests (for TestAddModel class)"""


this is used for all tests not just add_model

as-ondewo · 2026-01-14T11:49:06Z

test/testcases/test_http_api/test_user_models_management/conftest.py

+def cleanup_added_models(request: FixtureRequest, HttpApiAuth):
+    """Fixture to clean up models added during tests (for TestAddModel class)"""
+    # Track factories that might be added during tests
+    factories_to_cleanup: List[str] = ["Builtin", "LocalAI", "Ollama", "Xinference", "LM-Studio", "GPUStack", "FastEmbed"]


this is not an accurate list of the factories that are added in the tests

as-ondewo · 2026-01-14T12:00:21Z

test/testcases/test_http_api/common.py

    return session_ids
+
+
+# USER MODELS MANAGEMENT


The headers and data parameters of the functions here are used. Remove them.

as-ondewo · 2026-01-14T12:30:47Z

api/apps/sdk/users.py

+@manager.route("/models", methods=["POST"])  # noqa: F821
+@token_required
+async def add_model(tenant_id: str) -> Response:
+    """


The information in this docstring is wrong. Use the same docstring format as the other HTTP API endpoints. Additional details should be in the RAGFlow documentation.

as-ondewo · 2026-01-14T19:00:06Z

test/testcases/test_http_api/test_user_models_management/test_add_model.py

There are a lot of problems with the tests in this module, so I'll only focus on the parameter validation tests for now:

when testing a string parameter that needs to be present test 4 case: not providing the parameter at all, passing None, an empty string, and a string with only whitespace

make sure to construct your requests so that the reason they fail is related to what you are trying to test and not e.g. some unrelated missing parameter

The tests that test factories with special parameters are disorganized and partially redundant. Organize them into one TestSpecialParameterValidation class containing the following parameterized tests:

for each factory that has special parameters and can be added in "factory-mode" test the following when adding in factory mode (no llm_name or model_type):

providing all required parameters passes the validation (but request is still expected to fail when testing if model can be accessed)

for each of the special parameter test not providing it

for each special parameter test that providing it which a factory where it is not expected fails

for all factories that have special parameters add the same tests as described above also for adding individual models

for each factory without special parameters test that validation passes for a minimal valid config with any special parameter when adding in both factory-mode (for factories that support it) and individual mode (for all factories)

as-ondewo · 2026-01-14T19:04:27Z

api/utils/validation_utils.py

+    """Validation model for adding models (factory-level or individual model)."""
+
+    llm_factory: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1), Field(...)]
+    api_key: Annotated[str | dict[str, Any] | None, Field(default=None)]


Why can this be a dict?

as-ondewo · 2026-01-14T19:06:19Z

api/utils/validation_utils.py

 class ListDatasetReq(BaseListReq): ...
+
+
+class AddModelReq(Base):


strip whitespace for all string fields

as-ondewo · 2026-01-14T19:11:20Z

test/testcases/test_http_api/test_user_models_management/test_add_model.py

+        assert "model_type is required when adding an individual model" in res["message"], res
+
+    @pytest.mark.p1
+    def test_individual_model_invalid_model_type(self, HttpApiAuth: RAGFlowHttpApiAuth) -> None:


also test the success case for all of valid model types that should work

as-ondewo · 2026-01-14T19:26:13Z

test/testcases/test_http_api/test_user_models_management/test_add_model.py

+
+
+@pytest.mark.usefixtures("cleanup_added_models")
+class TestAddModelParameterValidation:


also test:

llm_name maximum length

api_key required for adding all models

base_url required for model without default base URL

max_tokens range of valid values

add implementation from OND211-2336

533721d

as-ondewo assigned hetavi-bluexkye Jan 2, 2026

as-ondewo mentioned this pull request Jan 8, 2026

Introduce User API Key Admin Endpoints and Model Configuration SDK API #4

Closed

Hetavi Shah added 3 commits January 9, 2026 19:50

[OND211-2350] Enhance model addition functionality with validation an…

2f39bf8

…d support for individual models and added tests for the add_model API.

[OND211-2350] Enhance add_model API with comprehensive validation for…

e11a4c4

… required fields across various factories. Added extensive test cases to ensure proper error handling for missing parameters.

[OND211-2350] Refactor test cases in test_add_model.py to include typ…

b2ad1ff

…e hints

as-ondewo commented Jan 14, 2026

View reviewed changes

		class ListDatasetReq(BaseListReq): ...


		class AddModelReq(Base):



		@pytest.mark.usefixtures("cleanup_added_models")
		class TestAddModelParameterValidation:

Add model management to RAGFlow HTTP API #6

Are you sure you want to change the base?

Add model management to RAGFlow HTTP API #6

Uh oh!

Conversation

as-ondewo commented Jan 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants