Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(llm): consolidate TTS / Seq2txt provider key resolution across 3 call sites (#17688)

Harsh Kashyapbe86baacca9a
diff --git a/rag/llm/key_utils.py b/rag/llm/key_utils.py
index 05255d79fb..01405ece89 100644
--- a/rag/llm/key_utils.py
+++ b/rag/llm/key_utils.py
@@ -14,6 +14,9 @@
# limitations under the License.
#
import json
+import logging
+
+from common.exceptions import ModelException
def _normalize_replicate_key(key):
@@ -31,4 +34,83 @@ def _normalize_replicate_key(key):
return key
-__all__ = ["_normalize_replicate_key"]
+def _resolve_provider_credentials(key):
+ """Parse a TTS / Seq2txt provider ``key`` and return the config dict.
+
+ Used by ``FishAudioTTS``, ``SparkTTS``, and ``TencentCloudSeq2txt``
+ (3 sites that previously did a bare ``key = json.loads(key)`` with
+ no try/except, no helper, and no fallback -- so a plain key
+ produced a raw ``JSONDecodeError`` and a JSON non-object produced
+ a raw ``AttributeError``).
+
+ The expected ``key`` is one of:
+
+ 1. A falsy value (``None`` or empty string) -- returns ``{}``.
+ 2. A Python ``dict`` -- returned verbatim. Covers the API verify
+ path that passes the form dict directly without JSON-encoding.
+ 3. A JSON-string-encoded object -- parsed and returned.
+
+ On non-JSON input -- for example a user pasting a plain API key
+ like ``"sk-..."`` -- raises a clear :class:`ModelException`
+ pointing at the expected schema, instead of letting
+ ``json.loads`` bubble up as ``json.decoder.JSONDecodeError`` from
+ inside the provider init.
+
+ On a JSON top-level type that is not a dict (list, string, number,
+ bool, null), raises the same clear :class:`ModelException`
+ instead of calling ``.get(...)`` on the value and getting
+ ``AttributeError``.
+
+ Returns a ``dict`` (possibly empty) on success.
+
+ This is the 8th helper in the JSON-decode family in this file
+ (alongside ``_resolve_bedrock_credentials``,
+ ``_resolve_qianfan_credentials``, ``_resolve_volcengine_credentials``,
+ ``_resolve_openrouter_credentials``,
+ ``_resolve_google_service_account_key``,
+ ``_resolve_azure_credentials``, ``_resolve_ocr_credentials``).
+ Unlike the OCR helper, this one does not have a separate
+ ``_is_raw_secret_key`` raw-key fallback -- the 3 sites covered
+ here (FishAudio, Spark, Tencent) do not support a raw key as a
+ documented api_key fallback, so a plain key is always a user
+ mistake and should surface as a clear error.
+ """
+ if not key:
+ return {}
+ if isinstance(key, dict):
+ return key
+ if isinstance(key, str):
+ try:
+ payload = json.loads(key)
+ except (json.JSONDecodeError, TypeError) as exc:
+ logging.warning(
+ 'TTS/Seq2txt provider key is not valid JSON; expected a JSON object (e.g. {"fish_audio_ak": "..."} for Fish Audio, or {"spark_app_id": "..."} for XunFei Spark). See conf/llm_factories.json for supported TTS / Seq2txt factories.',
+ )
+ raise ModelException(
+ 'TTS/Seq2txt provider key must be a JSON object. Example: {"fish_audio_ak": "..."} or {"spark_app_id": "..."} or {"tencent_cloud_sid": "..."}. See conf/llm_factories.json for supported TTS / Seq2txt factories.',
+ retryable=False,
+ ) from exc
+ else:
+ logging.warning(
+ "TTS/Seq2txt provider key is not a string or dict (got %s); expected a JSON object.",
+ type(key).__name__,
+ )
+ raise ModelException(
+ f"TTS/Seq2txt provider key must be a JSON object or string, got {type(key).__name__}. See conf/llm_factories.json for supported TTS / Seq2txt factories.",
+ retryable=False,
+ )
+
+ if not isinstance(payload, dict):
+ logging.warning(
+ "TTS/Seq2txt provider key parsed as JSON but is not a dict (got %s).",
+ type(payload).__name__,
+ )
+ raise ModelException(
+ f"TTS/Seq2txt provider key must be a JSON object, got {type(payload).__name__}. See conf/llm_factories.json for supported TTS / Seq2txt factories.",
+ retryable=False,
+ )
+
+ return payload
+
+
+__all__ = ["_normalize_replicate_key", "_resolve_provider_credentials"]
diff --git a/rag/llm/sequence2txt_model.py b/rag/llm/sequence2txt_model.py
index cb57f9f407..14588de794 100644
--- a/rag/llm/sequence2txt_model.py
+++ b/rag/llm/sequence2txt_model.py
@@ -30,6 +30,7 @@ from openai import OpenAI
from openai.lib.azure import AzureOpenAI
from common.token_utils import num_tokens_from_string
+from rag.llm.key_utils import _resolve_provider_credentials
from rag.utils.url_utils import append_api_path, ensure_v1
logger = logging.getLogger(__name__)
@@ -444,7 +445,10 @@ class TencentCloudSeq2txt(Base):
from tencentcloud.asr.v20190614 import asr_client
from tencentcloud.common import credential
- key = json.loads(key)
+ # Route key parsing through the shared helper. Pre-fix, the bare
+ # ``key = json.loads(key)`` crashed with raw JSONDecodeError on a
+ # plain key and AttributeError on a JSON non-object. See #17687.
+ key = _resolve_provider_credentials(key)
sid = key.get("tencent_cloud_sid", "")
sk = key.get("tencent_cloud_sk", "")
cred = credential.Credential(sid, sk)
diff --git a/rag/llm/tts_model.py b/rag/llm/tts_model.py
index becb8d3672..a850bf3b57 100644
--- a/rag/llm/tts_model.py
+++ b/rag/llm/tts_model.py
@@ -41,6 +41,7 @@ from pydantic import BaseModel, conint
from common.http_client import sync_request
from common.token_utils import num_tokens_from_string
from rag.utils.url_utils import ensure_v1
+from rag.llm.key_utils import _resolve_provider_credentials
class ServeReferenceAudio(BaseModel):
@@ -144,7 +145,10 @@ class FishAudioTTS(Base):
def __init__(self, key, model_name, base_url="https://api.fish.audio/v1/tts"):
if not base_url:
base_url = "https://api.fish.audio/v1/tts"
- key = json.loads(key)
+ # Route key parsing through the shared helper. Pre-fix, the bare
+ # ``key = json.loads(key)`` crashed with raw JSONDecodeError on a
+ # plain key and AttributeError on a JSON non-object. See #17687.
+ key = _resolve_provider_credentials(key)
self.headers = {
"api-key": key.get("fish_audio_ak"),
"content-type": "application/msgpack",
@@ -253,7 +257,10 @@ class SparkTTS(Base):
STATUS_LAST_FRAME = 2
def __init__(self, key, model_name, base_url=""):
- key = json.loads(key)
+ # Route key parsing through the shared helper. Pre-fix, the bare
+ # ``key = json.loads(key)`` crashed with raw JSONDecodeError on a
+ # plain key and AttributeError on a JSON non-object. See #17687.
+ key = _resolve_provider_credentials(key)
self.APPID = key.get("spark_app_id", "xxxxxxx")
self.APISecret = key.get("spark_api_secret", "xxxxxxx")
self.APIKey = key.get("spark_api_key", "xxxxxx")
diff --git a/test/unit_test/rag/llm/test_provider_credentials_three_sites.py b/test/unit_test/rag/llm/test_provider_credentials_three_sites.py
new file mode 100644
index 0000000000..66fa138675
--- /dev/null
+++ b/test/unit_test/rag/llm/test_provider_credentials_three_sites.py
@@ -0,0 +1,306 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Regression tests for the TTS / Seq2txt provider key JSON-decode gap
+across 3 sites (#17687).
+
+The 3 provider classes -- ``FishAudioTTS`` (TTS),
+``SparkTTS`` (TTS), and ``TencentCloudSeq2txt`` (Seq2txt) -- all
+parsed their ``key`` with a bare ``key = json.loads(key)``: no
+try/except, no helper, no fallback. When a user pasted a plain key,
+``json.loads`` raised ``JSONDecodeError`` and the exception
+propagated as a raw stack trace. When the user pasted a JSON
+non-object (list, string, number, null, bool),
+``key.get(field, default)`` raised ``AttributeError`` from inside
+the provider init.
+
+This test file covers two layers:
+
+ 1. The shared helper ``_resolve_provider_credentials`` in
+ :mod:`rag.llm.key_utils` (~14 tests): falsy key returns
+ ``{}``; Python dict passthrough; JSON dict happy path; JSON
+ array / string / number / float / null / bool all raise
+ ``ModelException``; plain string (most common user mistake)
+ raises ``ModelException``; empty string raises
+ ``ModelException``; invalid JSON raises ``ModelException``;
+ non-string non-dict (int, None, list) raises
+ ``ModelException``; helper is exported in ``__all__``.
+ 2. End-to-end on the 3 call sites (3 tests per site = 9 total):
+ JSON dict constructs with parsed fields, JSON array raises
+ ``ModelException``, and plain string raises
+ ``ModelException`` (the bug-fix case).
+
+The 3 sites do NOT support a raw secret key as a documented
+fallback (unlike Mistral/SoMark in the OCR family) -- a plain key
+is always a user mistake and should surface as a clear error.
+"""
+
+import json
+
+import pytest
+
+from common.exceptions import ModelException
+from rag.llm.key_utils import _resolve_provider_credentials
+from rag.llm.sequence2txt_model import TencentCloudSeq2txt
+from rag.llm.tts_model import FishAudioTTS, SparkTTS
+
+
+# --------------------------------------------------------------------------- #
+# 1. The shared helper
+# --------------------------------------------------------------------------- #
+
+
+class TestResolveProviderCredentials:
+ """``_resolve_provider_credentials`` parses a TTS / Seq2txt
+ provider key into a config ``dict``. Falsy / dict /
+ JSON-string-encoded dict inputs succeed; everything else
+ raises ``ModelException`` with a clear message pointing at the
+ expected schema.
+ """
+
+ def test_falsy_key_returns_empty_dict(self):
+ assert _resolve_provider_credentials("") == {}
+ assert _resolve_provider_credentials(None) == {}
+
+ def test_python_dict_passes_through(self):
+ out = _resolve_provider_credentials({"fish_audio_ak": "x"})
+ assert out == {"fish_audio_ak": "x"}
+
+ def test_json_dict_with_all_fields(self):
+ raw = {"fish_audio_ak": "x", "fish_audio_refid": "r"}
+ out = _resolve_provider_credentials(json.dumps(raw))
+ assert out == raw
+
+ def test_json_array_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials(json.dumps(["not", "a", "key"]))
+ msg = str(exc_info.value)
+ assert "TTS/Seq2txt provider key" in msg
+ assert "object" in msg
+ assert "list" in msg
+ assert "AttributeError" not in msg
+ assert exc_info.value.retryable is False
+
+ def test_json_string_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials(json.dumps("just a string"))
+ assert "object" in str(exc_info.value)
+ assert "str" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_json_number_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials(json.dumps(42))
+ assert "object" in str(exc_info.value)
+ assert "int" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_json_float_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials(json.dumps(3.14))
+ assert "object" in str(exc_info.value)
+ assert "float" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_json_null_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials("null")
+ assert "object" in str(exc_info.value)
+ assert "NoneType" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_json_bool_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials("true")
+ assert "object" in str(exc_info.value)
+ assert "bool" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_plain_string_raises_model_exception(self):
+ """The most common user mistake: pasting a plain API key from
+ the provider's portal. Pre-fix this was a raw
+ ``JSONDecodeError: Expecting value: line 1 column 1 (char
+ 0)``. The fix raises a clear ``ModelException``.
+ """
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials("sk-abc12345-very-long-api-key")
+ msg = str(exc_info.value)
+ assert "TTS/Seq2txt provider key" in msg
+ assert "JSON object" in msg
+ assert "JSONDecodeError" not in msg
+ assert "Expecting value" not in msg
+ assert exc_info.value.retryable is False
+
+ def test_invalid_json_string_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ _resolve_provider_credentials("not really json {")
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "JSON" in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_non_string_non_dict_input_raises_model_exception(self):
+ """A list / int / tuple / None (non-empty) / etc. passed directly
+ (not as a string or dict) must also raise. Only ``str`` and
+ ``dict`` are valid inputs to the helper.
+ """
+ for bad in (42, ["a", "b"], (1, 2), 3.14, True):
+ with pytest.raises(ModelException):
+ _resolve_provider_credentials(bad)
+
+ def test_empty_dict_returns_empty_dict(self):
+ """An empty dict is a valid input (no config) and returns an
+ empty dict -- the caller is responsible for handling it.
+ """
+ assert _resolve_provider_credentials({}) == {}
+
+ def test_helper_lists_in_its_module_all(self):
+ """The helper must be exported from ``rag.llm.key_utils``."""
+ from rag.llm import key_utils
+
+ assert "_resolve_provider_credentials" in key_utils.__all__
+
+
+# --------------------------------------------------------------------------- #
+# 2. End-to-end: 3 call sites
+# --------------------------------------------------------------------------- #
+
+
+class TestFishAudioTTSCallSite:
+ """``FishAudioTTS`` (TTS) requires a JSON config. Pre-fix, a
+ bare ``key = json.loads(key)`` raised raw ``JSONDecodeError`` on
+ a plain key and raw ``AttributeError`` on a JSON non-object.
+ The fix raises a clear ``ModelException``.
+ """
+
+ def test_json_dict_constructs_with_parsed_fields(self):
+ mdl = FishAudioTTS(
+ key=json.dumps({"fish_audio_ak": "ak-value", "fish_audio_refid": "ref-value"}),
+ model_name="fish-audio-model",
+ )
+ assert mdl.headers["api-key"] == "ak-value"
+ assert mdl.ref_id == "ref-value"
+
+ def test_json_array_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ FishAudioTTS(key=json.dumps(["not", "a", "key"]), model_name="m")
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "object" in str(exc_info.value)
+ assert "list" in str(exc_info.value)
+ assert "AttributeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_plain_string_raises_model_exception(self):
+ """The bug-fix case: a plain API key used to raise a raw
+ ``JSONDecodeError``. Now it raises a clear ``ModelException``.
+ """
+ with pytest.raises(ModelException) as exc_info:
+ FishAudioTTS(
+ key="sk-abc12345-very-long-fish-audio-key",
+ model_name="m",
+ )
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "JSON object" in str(exc_info.value)
+ assert "JSONDecodeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+
+class TestSparkTTSCallSite:
+ """``SparkTTS`` (XunFei Spark TTS) requires a JSON config.
+ Pre-fix, a bare ``key = json.loads(key)`` raised raw
+ ``JSONDecodeError`` on a plain key. The fix raises.
+ """
+
+ def test_json_dict_constructs_with_parsed_fields(self):
+ mdl = SparkTTS(
+ key=json.dumps(
+ {
+ "spark_app_id": "app-id",
+ "spark_api_secret": "api-secret",
+ "spark_api_key": "api-key",
+ }
+ ),
+ model_name="spark-model",
+ )
+ assert mdl.APPID == "app-id"
+ assert mdl.APISecret == "api-secret"
+ assert mdl.APIKey == "api-key"
+
+ def test_json_array_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ SparkTTS(key=json.dumps(["not", "a", "key"]), model_name="m")
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "object" in str(exc_info.value)
+ assert "list" in str(exc_info.value)
+ assert "AttributeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_plain_string_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ SparkTTS(
+ key="sk-abc12345-very-long-spark-api-key",
+ model_name="m",
+ )
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "JSON object" in str(exc_info.value)
+ assert "JSONDecodeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+
+class TestTencentCloudSeq2txtCallSite:
+ """``TencentCloudSeq2txt`` (Tencent Cloud ASR) requires a JSON
+ config. Pre-fix, a bare ``key = json.loads(key)`` raised raw
+ ``JSONDecodeError`` on a plain key. The fix raises.
+ """
+
+ def test_json_dict_constructs_with_parsed_fields(self):
+ mdl = TencentCloudSeq2txt(
+ key=json.dumps(
+ {
+ "tencent_cloud_sid": "sid-value",
+ "tencent_cloud_sk": "sk-value",
+ }
+ ),
+ model_name="16k_zh",
+ )
+ assert mdl.model_name == "16k_zh"
+ # The Tencent SDK stores credentials internally; we just
+ # check that construction succeeded without raising, which
+ # implies the JSON was parsed and the credentials were
+ # extracted without AttributeError.
+ assert mdl.client is not None
+
+ def test_json_array_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ TencentCloudSeq2txt(
+ key=json.dumps(["not", "a", "key"]),
+ model_name="16k_zh",
+ )
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "object" in str(exc_info.value)
+ assert "list" in str(exc_info.value)
+ assert "AttributeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False
+
+ def test_plain_string_raises_model_exception(self):
+ with pytest.raises(ModelException) as exc_info:
+ TencentCloudSeq2txt(
+ key="sk-abc12345-very-long-tencent-sid",
+ model_name="16k_zh",
+ )
+ assert "TTS/Seq2txt provider key" in str(exc_info.value)
+ assert "JSON object" in str(exc_info.value)
+ assert "JSONDecodeError" not in str(exc_info.value)
+ assert exc_info.value.retryable is False