Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
## [Unreleased]
- 긴 이메일·첨부 본문을 의미 단위 청크로 임베딩한 뒤 기존 email/attachment 벡터 계약으로 평균화하고, OpenAI `text-embedding-3-*`에는 저장 차원(`1536`)을 직접 요청하도록 보강했습니다. 합성 메일 fixture 5건(70청크)과 provider 요청 계약으로 1,536차원 벡터 경로를 검증했으며, 회사 기밀 메일·첨부 바이트는 외부로 전송하지 않습니다.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- EmailDetail 테스트가 지원하지 않는 스레드 병합/분리 버튼을 `textContent`뿐 아니라 `aria-label`과 `title` 접근 가능 이름으로도 검출하도록 바꿔, 아이콘 전용 버튼 회귀를 놓치지 않습니다.

### 캘린더 충돌 (Status-weighted conflicts)
Expand Down
54 changes: 49 additions & 5 deletions backend/services/email_import_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
from services.email_parser import EmailData, parse_eml_bytes
from services.embedding import (
STORAGE_EMBEDDING_DIMENSION,
chunk_text,
fit_embedding_vector,
generate_embeddings,
)
Expand All @@ -52,7 +53,10 @@

EMBEDDING_DIMENSION = STORAGE_EMBEDDING_DIMENSION
MAX_IMPORT_UPLOADS = 10
MAX_IMPORT_UPLOAD_BYTES = 20 * 1024 * 1024
# Transport safety ceiling only; parser and embedding chunking must accept
# sources larger than 20 MiB without confusing the request guard for a parser
# limit.
MAX_IMPORT_UPLOAD_BYTES = 64 * 1024 * 1024
MAX_IMPORT_EML_FILES = 100
MAX_IMPORT_EMAILS_PER_OWNER = 1000
MAX_UPLOAD_FILENAME_DECODE_ROUNDS = 8
Expand Down Expand Up @@ -288,18 +292,56 @@ async def _extract_and_generate_embeddings(
batch_context: "EmailImportBatchContext | None" = None,
) -> tuple[list[dict], list[list[float]]]:
attachment_payloads = list(parsed.get("attachments", []))
embedding_texts = [str(parsed.get("body") or "")]
embedding_texts.extend(
str(attachment.get("content") or "") for attachment in attachment_payloads
source_texts = [str(parsed.get("body") or "")]
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
source_texts.extend(
str(
""
if (attachment.get("parse_status") or "parsed") != "parsed"
else (
attachment.get("parse_content")
if attachment.get("parse_content") is not None
else attachment.get("content") or ""
)
)
for attachment in attachment_payloads
)
fitted_embeddings = await _generate_import_embeddings(
embedding_texts, chunk_counts = _chunk_import_texts(source_texts)
chunk_embeddings = await _generate_import_embeddings(
embedding_texts,
embedding_provider=embedding_provider,
batch_context=batch_context,
)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
fitted_embeddings: list[list[float]] = []
offset = 0
for chunk_count in chunk_counts:
fitted_embeddings.append(
_mean_embedding(chunk_embeddings[offset : offset + chunk_count])
)
offset += chunk_count
return attachment_payloads, fitted_embeddings


def _chunk_import_texts(texts: list[str]) -> tuple[list[str], list[int]]:
"""Split each email/attachment into semantic-sized embedding inputs."""
chunks: list[str] = []
chunk_counts: list[int] = []
for text in texts:
source_chunks = chunk_text(text)
chunks.extend(source_chunks)
chunk_counts.append(len(source_chunks))
return chunks, chunk_counts


def _mean_embedding(embeddings: list[list[float]]) -> list[float]:
"""Average chunk vectors into the existing one-vector record contract."""
if not embeddings:
return _zero_embedding()
return [
sum(vector[index] for vector in embeddings) / len(embeddings)
for index in range(len(embeddings[0]))
]


def _build_email_object(
*,
parsed: EmailData,
Expand Down Expand Up @@ -905,6 +947,8 @@ async def _generate_import_embeddings(
embedding_provider: EmailImportEmbeddingProvider | None,
batch_context: "EmailImportBatchContext | None" = None,
) -> list[list[float]]:
if not texts:
return []
if embedding_provider is None:
return [_zero_embedding() for _ in texts]
if batch_context is not None and texts:
Expand Down
14 changes: 11 additions & 3 deletions backend/services/embedding.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,11 @@ def fit_embedding_vector(
return embedding[:target_dimension]


def _supports_native_dimensions(model: str) -> bool:
"""Return whether the selected OpenAI embedding family accepts dimensions."""
return model.rsplit("/", 1)[-1].startswith("text-embedding-3-")


async def generate_embeddings(
texts: list[str],
openai_api_key: str,
Expand All @@ -56,13 +61,16 @@ async def generate_embeddings(
http_client=http_client,
)

selected_model = model or settings.OPENAI_EMBEDDING_MODEL
request = {"model": selected_model, "input": texts}
if _supports_native_dimensions(selected_model):
request["dimensions"] = STORAGE_EMBEDDING_DIMENSION

try:
response = await provider_circuit_breaker.call(
validated_base_url or "openai-default",
lambda: retry_transient(
lambda: client.embeddings.create(
model=model or settings.OPENAI_EMBEDDING_MODEL, input=texts
),
lambda: client.embeddings.create(**request),
operation_name="embedding generation",
),
)
Expand Down
90 changes: 90 additions & 0 deletions backend/tests/test_email_import_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@
)


def test_import_transport_ceiling_accepts_sources_over_20_mib():
assert email_import_module.MAX_IMPORT_UPLOAD_BYTES > 20 * 1024 * 1024


@pytest.mark.parametrize(
"input_name,expected",
[
Expand Down Expand Up @@ -546,6 +550,92 @@ async def test_generate_import_embeddings_logs_non_secret_provider_fallback(capl
assert "embeddinggemma" not in caplog.text


@pytest.mark.asyncio
async def test_extract_embeddings_chunks_long_sources_and_averages_vectors():
provider = EmailImportEmbeddingProvider(
api_key="provider-key",
base_url="https://provider.example/v1",
embedding_model="text-embedding-3-large",
)
captured_texts: list[str] = []

async def fake_generate(texts, *, embedding_provider, batch_context=None):
captured_texts.extend(texts)
return [[float(index)] * EMBEDDING_DIMENSION for index in range(1, len(texts) + 1)]

parsed = {
"body": "body paragraph " * 500,
"attachments": [{"content": "short attachment"}, {"content": ""}],
}
with patch(
"services.email_import_service._generate_import_embeddings",
side_effect=fake_generate,
):
_, embeddings = await email_import_module._extract_and_generate_embeddings(
parsed,
provider,
)

body_chunk_count = len(captured_texts) - 1
assert body_chunk_count > 1
assert len(embeddings) == 3
assert "" not in captured_texts
assert embeddings[0][0] == sum(range(1, body_chunk_count + 1)) / body_chunk_count
assert embeddings[1][0] == float(len(captured_texts))
assert embeddings[2] == [0.0] * EMBEDDING_DIMENSION


@pytest.mark.asyncio
async def test_extract_embeddings_does_not_chunk_pending_attachment_payload():
captured_texts: list[str] = []

async def fake_generate(texts, *, embedding_provider, batch_context=None):
captured_texts.extend(texts)
return []

parsed = {
"body": "",
"attachments": [
{
"content": "cHJpdmF0ZS1wZGYtYnl0ZXM=",
"parse_status": "pdf_dom_recognition_pending",
}
],
}
with patch(
"services.email_import_service._generate_import_embeddings",
side_effect=fake_generate,
):
_, embeddings = await email_import_module._extract_and_generate_embeddings(
parsed,
embedding_provider=None,
)

assert captured_texts == []
assert embeddings == [[0.0] * EMBEDDING_DIMENSION, [0.0] * EMBEDDING_DIMENSION]


@pytest.mark.asyncio
async def test_extract_embeddings_skips_provider_for_empty_sources():
provider = EmailImportEmbeddingProvider(
api_key="provider-key",
base_url="https://provider.example/v1",
embedding_model="text-embedding-3-large",
)

with patch(
"services.email_import_service.generate_embeddings",
new_callable=AsyncMock,
) as mock_generate_embeddings:
_, embeddings = await email_import_module._extract_and_generate_embeddings(
{"body": "", "attachments": []},
provider,
)

mock_generate_embeddings.assert_not_awaited()
assert embeddings == [[0.0] * EMBEDDING_DIMENSION]


@pytest.mark.asyncio
async def test_generate_import_embeddings_recovers_valid_items_after_batch_failure():
provider = EmailImportEmbeddingProvider(
Expand Down
32 changes: 32 additions & 0 deletions backend/tests/test_embedding.py
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,38 @@ async def test_generate_embeddings_uses_selected_provider_model_and_base_url():
mock_client.close.assert_awaited_once()


@pytest.mark.asyncio
async def test_generate_embeddings_requests_storage_dimensions_for_openai_v3():
with patch(
"services.embedding.AsyncOpenAI"
) as mock_async_openai, patch(
"services.embedding.build_llm_provider_http_client",
new_callable=AsyncMock,
) as mock_build_client:
mock_build_client.return_value = ("https://api.openai.com/v1", AsyncMock())
mock_client = mock_async_openai.return_value
mock_client.close = AsyncMock()
mock_client.embeddings.create = AsyncMock()
mock_response = AsyncMock()
mock_data = AsyncMock()
mock_data.embedding = [0.1, 0.2]
mock_response.data = [mock_data]
mock_client.embeddings.create.return_value = mock_response

await generate_embeddings(
["test"],
"provider-key",
base_url="https://api.openai.com/v1",
model="text-embedding-3-large",
)

mock_client.embeddings.create.assert_awaited_once_with(
model="text-embedding-3-large",
input=["test"],
dimensions=STORAGE_EMBEDDING_DIMENSION,
)


@pytest.mark.asyncio
async def test_generate_embeddings_api_error():
with patch(
Expand Down
Loading