A community-supported supercharged document management system: scan, index and archive all your documents
Python aiangulararchivingdjangodmsdocument-managementdocument-management-systemllmmachine-learningocroptical-character-recognitionpdf
Enhancement: support separate embedding API key (#14067)
Furkan URALe34eda07bbc1
diff --git a/docs/advanced_usage.md b/docs/advanced_usage.mdindex 661c2d704..105add465 100644--- a/docs/advanced_usage.md+++ b/docs/advanced_usage.md@@ -153,8 +153,11 @@ in similar existing documents, and the document chat can retrieve relevant conteEnable it by setting[`PAPERLESS_AI_LLM_EMBEDDING_BACKEND`](configuration.md#PAPERLESS_AI_LLM_EMBEDDING_BACKEND)-(`huggingface` for fully-local embeddings, or `ollama` / `openai-like`). The index is only-built when AI is enabled **and** an embedding backend is set.+(`huggingface` for fully-local embeddings, or `ollama` / `openai-like`). By default, the main+LLM API key and endpoint are used, but an optional embedding-specific[API key](configuration.md#PAPERLESS_AI_LLM_EMBEDDING_API_KEY)+and [endpoint](configuration.md#PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT) can be configured.++The index is only built when AI is enabled **and** an embedding backend is set.The index is updated automatically on a schedule controlled by[`PAPERLESS_LLM_INDEX_TASK_CRON`](configuration.md#PAPERLESS_LLM_INDEX_TASK_CRON) (daily bydiff --git a/docs/configuration.md b/docs/configuration.mdindex f48291824..2f94c41aa 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -2133,6 +2133,13 @@ for language and resource considerations.Defaults to None.+#### [`PAPERLESS_AI_LLM_EMBEDDING_API_KEY=<str>`](#PAPERLESS_AI_LLM_EMBEDDING_API_KEY) {#PAPERLESS_AI_LLM_EMBEDDING_API_KEY}++: The API key to use for the embedding backend. If not supplied, embeddings use+`PAPERLESS_AI_LLM_API_KEY`.++ Defaults to None.+#### [`PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT=<str>`](#PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT) {#PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT}: The endpoint / url to use for the embedding backend. If not supplied, embeddings usediff --git a/src-ui/src/app/data/paperless-config.ts b/src-ui/src/app/data/paperless-config.tsindex 690d7aa4e..2568358bd 100644--- a/src-ui/src/app/data/paperless-config.ts+++ b/src-ui/src/app/data/paperless-config.ts@@ -353,6 +353,14 @@ export const PaperlessConfigOptions: ConfigOption[] = [config_key: 'PAPERLESS_AI_LLM_EMBEDDING_MODEL',category: ConfigCategory.AI,},+ {+ key: 'llm_embedding_api_key',+ title: $localize`LLM Embedding API Key`,+ type: ConfigOptionType.Password,+ note: $localize`Used for embeddings when set, otherwise LLM API key is used.`,+ config_key: 'PAPERLESS_AI_LLM_EMBEDDING_API_KEY',+ category: ConfigCategory.AI,+ },{key: 'llm_embedding_endpoint',title: $localize`LLM Embedding Endpoint`,@@ -457,6 +465,7 @@ export interface PaperlessConfig extends ObjectWithId {ai_enabled: booleanllm_embedding_backend: stringllm_embedding_model: string+ llm_embedding_api_key: stringllm_embedding_endpoint: stringllm_embedding_chunk_size: numberllm_context_size: numberdiff --git a/src/documents/tests/test_api_app_config.py b/src/documents/tests/test_api_app_config.pyindex ab05135aa..4566d668d 100644--- a/src/documents/tests/test_api_app_config.py+++ b/src/documents/tests/test_api_app_config.py@@ -81,6 +81,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):"ai_enabled": None,"llm_embedding_backend": None,"llm_embedding_model": None,+ "llm_embedding_api_key": None,"llm_embedding_endpoint": None,"llm_embedding_chunk_size": None,"llm_context_size": None,@@ -922,6 +923,49 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):self.assertEqual(response.status_code, status.HTTP_405_METHOD_NOT_ALLOWED)self.assertEqual(ApplicationConfiguration.objects.count(), 1)+ def test_update_llm_embedding_api_key(self) -> None:+ """+ GIVEN:+ - Existing config with llm_embedding_api_key specified+ WHEN:+ - API to update llm_embedding_api_key is called with all *s+ - API to update llm_embedding_api_key is called with empty string+ THEN:+ - llm_embedding_api_key is unchanged+ - llm_embedding_api_key is set to None+ """+ config = ApplicationConfiguration.objects.first()+ assert config is not None+ config.llm_embedding_api_key = "1234567890"+ config.save()++ # Test with all *+ response = self.client.patch(+ f"{self.ENDPOINT}1/",+ json.dumps(+ {+ "llm_embedding_api_key": "*" * 32,+ },+ ),+ content_type="application/json",+ )+ self.assertEqual(response.status_code, status.HTTP_200_OK)+ config.refresh_from_db()+ self.assertEqual(config.llm_embedding_api_key, "1234567890")+ # Test with empty string+ response = self.client.patch(+ f"{self.ENDPOINT}1/",+ json.dumps(+ {+ "llm_embedding_api_key": "",+ },+ ),+ content_type="application/json",+ )+ self.assertEqual(response.status_code, status.HTTP_200_OK)+ config.refresh_from_db()+ self.assertEqual(config.llm_embedding_api_key, None)+def test_update_llm_api_key(self) -> None:"""GIVEN:diff --git a/src/paperless/config.py b/src/paperless/config.pyindex 5506d1fbd..116b18dde 100644--- a/src/paperless/config.py+++ b/src/paperless/config.py@@ -245,6 +245,7 @@ class AIConfig(BaseConfig):ai_enabled: bool = dataclasses.field(init=False)llm_embedding_backend: str = dataclasses.field(init=False)llm_embedding_model: str = dataclasses.field(init=False)+ llm_embedding_api_key: str = dataclasses.field(init=False)llm_embedding_endpoint: str = dataclasses.field(init=False)llm_embedding_chunk_size: int = dataclasses.field(init=False)llm_context_size: int = dataclasses.field(init=False)@@ -271,6 +272,9 @@ class AIConfig(BaseConfig):self.llm_embedding_model = (app_config.llm_embedding_model or settings.LLM_EMBEDDING_MODEL)+ self.llm_embedding_api_key = (+ app_config.llm_embedding_api_key or settings.LLM_EMBEDDING_API_KEY+ )self.llm_embedding_endpoint = (app_config.llm_embedding_endpoint or settings.LLM_EMBEDDING_ENDPOINT)diff --git a/src/paperless/migrations/0017_applicationconfiguration_llm_embedding_api_key.py b/src/paperless/migrations/0017_applicationconfiguration_llm_embedding_api_key.pynew file mode 100644index 000000000..28259e447--- /dev/null+++ b/src/paperless/migrations/0017_applicationconfiguration_llm_embedding_api_key.py@@ -0,0 +1,23 @@+# Generated by Django 5.2.16 on 2026-09-11 09:32++from django.db import migrations+from django.db import models+++class Migration(migrations.Migration):+ dependencies = [+ ("paperless", "0016_alter_applicationconfiguration_ai_enabled"),+ ]++ operations = [+ migrations.AddField(+ model_name="applicationconfiguration",+ name="llm_embedding_api_key",+ field=models.CharField(+ blank=True,+ max_length=1024,+ null=True,+ verbose_name="Sets the LLM embedding API key",+ ),+ ),+ ]diff --git a/src/paperless/models.py b/src/paperless/models.pyindex 64fc45fc0..480b8629f 100644--- a/src/paperless/models.py+++ b/src/paperless/models.py@@ -365,6 +365,13 @@ class ApplicationConfiguration(AbstractSingletonModel):max_length=128,)+ llm_embedding_api_key = models.CharField(+ verbose_name=_("Sets the LLM embedding API key"),+ blank=True,+ null=True,+ max_length=1024,+ )+llm_embedding_endpoint = models.CharField(verbose_name=_("Sets the LLM embedding endpoint, optional"),blank=True,diff --git a/src/paperless/serialisers.py b/src/paperless/serialisers.pyindex 7b32230f8..6430df889 100644--- a/src/paperless/serialisers.py+++ b/src/paperless/serialisers.py@@ -216,6 +216,11 @@ class ApplicationConfigurationSerializer(externally_configured_variables = serializers.SerializerMethodField()user_args = serializers.JSONField(binary=True, allow_null=True)barcode_tag_mapping = serializers.JSONField(binary=True, allow_null=True)+ llm_embedding_api_key = ObfuscatedPasswordField(+ required=False,+ allow_null=True,+ max_length=1024,+ )llm_api_key = ObfuscatedPasswordField(required=False,allow_null=True,@@ -227,7 +232,11 @@ class ApplicationConfigurationSerializer(max_length=1024,)- OBFUSCATED_FIELDS = ("llm_api_key", "remote_ocr_api_key")+ OBFUSCATED_FIELDS = (+ "llm_embedding_api_key",+ "llm_api_key",+ "remote_ocr_api_key",+ )def get_externally_configured_variables(self,diff --git a/src/paperless/settings/__init__.py b/src/paperless/settings/__init__.pyindex a9a57a6b3..0de6d32e4 100644--- a/src/paperless/settings/__init__.py+++ b/src/paperless/settings/__init__.py@@ -1236,6 +1236,7 @@ LLM_EMBEDDING_BACKEND = get_choice_from_env({"huggingface", "openai-like", "ollama"},)LLM_EMBEDDING_MODEL = os.getenv("PAPERLESS_AI_LLM_EMBEDDING_MODEL")+LLM_EMBEDDING_API_KEY = os.getenv("PAPERLESS_AI_LLM_EMBEDDING_API_KEY")LLM_EMBEDDING_ENDPOINT = os.getenv("PAPERLESS_AI_LLM_EMBEDDING_ENDPOINT")LLM_EMBEDDING_CHUNK_SIZE = get_int_from_env("PAPERLESS_AI_LLM_EMBEDDING_CHUNK_SIZE",diff --git a/src/paperless/tests/test_config_precedence.py b/src/paperless/tests/test_config_precedence.pyindex 2cc9aecf3..0b439dd1f 100644--- a/src/paperless/tests/test_config_precedence.py+++ b/src/paperless/tests/test_config_precedence.py@@ -30,3 +30,27 @@ class TestBooleanConfigPrecedence(TestCase):config.save()self.assertTrue(AIConfig().ai_enabled)+++class TestAIConfigPrecedence(TestCase):+ @override_settings(LLM_EMBEDDING_API_KEY="environment-embedding-key")+ def test_database_embedding_api_key_overrides_environment_setting(self) -> None:+ config, _ = ApplicationConfiguration.objects.get_or_create()+ config.llm_embedding_api_key = "database-embedding-key"+ config.save()++ self.assertEqual(+ AIConfig().llm_embedding_api_key,+ "database-embedding-key",+ )++ @override_settings(LLM_EMBEDDING_API_KEY="environment-embedding-key")+ def test_null_embedding_api_key_uses_environment_setting(self) -> None:+ config, _ = ApplicationConfiguration.objects.get_or_create()+ config.llm_embedding_api_key = None+ config.save()++ self.assertEqual(+ AIConfig().llm_embedding_api_key,+ "environment-embedding-key",+ )diff --git a/src/paperless_ai/embedding.py b/src/paperless_ai/embedding.pyindex dbbb2b3be..0fd71423f 100644--- a/src/paperless_ai/embedding.py+++ b/src/paperless_ai/embedding.py@@ -41,7 +41,9 @@ def get_embedding_model(config: AIConfig) -> "BaseEmbedding":)return OpenAILikeEmbedding(model_name=config.llm_embedding_model or "text-embedding-3-small",- api_key=config.llm_api_key or PLACEHOLDER_API_KEY,+ api_key=config.llm_embedding_api_key+ or config.llm_api_key+ or PLACEHOLDER_API_KEY,api_base=endpoint,timeout=config.llm_request_timeout,http_client=http_client,diff --git a/src/paperless_ai/tests/test_embedding.py b/src/paperless_ai/tests/test_embedding.pyindex 1373a37bd..126a1a9f3 100644--- a/src/paperless_ai/tests/test_embedding.py+++ b/src/paperless_ai/tests/test_embedding.py@@ -17,6 +17,7 @@ from paperless_ai.embedding import get_embedding_model@pytest.fixturedef mock_ai_config():with patch("paperless_ai.embedding.AIConfig") as MockAIConfig:+ MockAIConfig.return_value.llm_embedding_api_key = NoneMockAIConfig.return_value.llm_embedding_endpoint = NoneMockAIConfig.return_value.llm_allow_internal_endpoints = TrueMockAIConfig.return_value.llm_context_size = 8192@@ -63,6 +64,7 @@ def mock_document():def test_get_embedding_model_openai(mock_ai_config):mock_ai_config.return_value.llm_embedding_backend = LLMEmbeddingBackend.OPENAI_LIKEmock_ai_config.return_value.llm_embedding_model = "text-embedding-3-small"+ mock_ai_config.return_value.llm_embedding_api_key = "test_embedding_api_key"mock_ai_config.return_value.llm_api_key = "test_api_key"mock_ai_config.return_value.llm_endpoint = "http://test-url"@@ -72,7 +74,7 @@ def test_get_embedding_model_openai(mock_ai_config):model = get_embedding_model(mock_ai_config.return_value)MockOpenAIEmbedding.assert_called_once_with(model_name="text-embedding-3-small",- api_key="test_api_key",+ api_key="test_embedding_api_key",api_base="http://test-url",timeout=120,http_client=ANY,@@ -81,6 +83,20 @@ def test_get_embedding_model_openai(mock_ai_config):assert model == MockOpenAIEmbedding.return_value+def test_get_embedding_model_openai_falls_back_to_llm_api_key(mock_ai_config):+ mock_ai_config.return_value.llm_embedding_backend = LLMEmbeddingBackend.OPENAI_LIKE+ mock_ai_config.return_value.llm_embedding_model = "text-embedding-3-small"+ mock_ai_config.return_value.llm_api_key = "test_api_key"+ mock_ai_config.return_value.llm_endpoint = "http://test-url"++ with patch(+ "llama_index.embeddings.openai_like.OpenAILikeEmbedding",+ ) as MockOpenAIEmbedding:+ get_embedding_model(mock_ai_config.return_value)++ assert MockOpenAIEmbedding.call_args.kwargs["api_key"] == "test_api_key"++@pytest.mark.parametrize("configured_key", [None, ""])def test_get_embedding_model_openai_without_api_key_sends_placeholder(mock_ai_config,@@ -89,6 +105,7 @@ def test_get_embedding_model_openai_without_api_key_sends_placeholder("""Same required key handling as the LLM client, see #13831."""mock_ai_config.return_value.llm_embedding_backend = LLMEmbeddingBackend.OPENAI_LIKEmock_ai_config.return_value.llm_embedding_model = "text-embedding-3-small"+ mock_ai_config.return_value.llm_embedding_api_key = configured_keymock_ai_config.return_value.llm_api_key = configured_keymock_ai_config.return_value.llm_endpoint = "http://test-url"