docs(S15P11A705-96): Embedding Profile의 정본을 코드로 옮긴다 (7.1)

[colosair]

요약

05_AI_설계.md 7.1의 Profile 주입 규정을 바꿉니다. 정본을 배포 설정에서 FastAPI 코드 기본값으로 옮기고, 환경변수 주입은 실험·롤백용 덮어쓰기로 낮춥니다. 문서 한 절만 바뀌며 코드·스키마 변경은 이 PR에 없습니다.

이 문서는 파트 간 계약이라 백엔드 확인 후 머지하겠습니다. 구현은 ai 레포에 별도 PR로 준비돼 있고 이 PR이 선행입니다.

Jira

• S15P11A705-96 — [AI] dev 배포용 GMS·모델·bootstrap·관측 계약 확정
• https://ssafy.atlassian.net/browse/S15P11A705-96

배경 — 왜 지금 바뀌나

인프라 배포 준비로 PINLOG_EMBEDDING_* 넷을 GitHub Actions Secret에 등록하면서 드러났습니다.

Profile 변경은 기존 Embedding을 전부 조회 대상에서 빼는 결정입니다(9.3 검색 필터의 embedding_profile 일치 조건). 그런데 현 규정대로면 그것이 배포 콘솔 편집 한 번으로 가능합니다 — PR도, 리뷰도, "누가 언제 왜 바꿨나"의 기록도 없이. 게다가 값 자체는 7.1 표에 이미 공개돼 있어 숨겨진 적도 없습니다.

공개 값을 비밀처럼 다루면 보안은 늘지 않고 감시만 줄어듭니다.

변경 사항

위치	전 → 후
7.1 세 번째 불릿	"Spring과 FastAPI에 각각 하드코딩하지 않습니다" → 정본은 FastAPI 설정 기본값, 주입은 덮어쓰기
7.1 네 번째 불릿	"배포 환경의 단일 설정에서 주입합니다" → 런타임 대조가 이중화를 막는다는 서술
7.1 (신설)	Spring이 값을 어디서 얻을지는 -135 시점에 정한다
7.1 (신설)	개정 사실과 원문을 인용문으로 보존

설계 결정 — 기각한 대안

원 규정 유지. *"기본값이 있으면 배포 설정 누락이 조용한 Profile 불일치로 나타난다"*가 원 논거였습니다. 그러나 그 논거는 주입이 필수라는 전제 위에 있습니다. 주입을 덮어쓰기로 돌리면 기본값으로 뜨는 것이 정상 동작이므로 "누락"이라는 상태 자체가 없어집니다.

config/*.yaml 계층 도입. 공개/비공개 분리라는 목적은 같게 달성하지만 설정 소스가 셋(yaml → env → Secret)이 됩니다. 장애를 볼 때마다 "이 값이 어디서 왔나"를 역추적해야 해서, 얻는 것보다 잃는 추적 가능성이 큽니다.

검증

• 참조 실재 확인 — 인용한 9.3 검색 필터의 embedding_profile 일치 조건이 실제로 있는지 대조했습니다. (초안에 11.4로 적었다가 그 절이 존재하지 않는 것을 발견해 고쳤습니다 — 422 처리는 공용 계약이 아니라 ai 레포 명세 3.1에 있습니다)
• 값 일치 — 7.1 표의 값과 ai 레포 코드 기본값이 같음
• 코드 변경 해당 없음 — 이 PR은 문서 한 절입니다

리뷰 포인트

1. 이중화 방지 장치가 충분한가. 원 규정이 막으려던 것은 "두 파트가 서로 다른 Profile을 갖는 것"이고, 이제 그 역할을 런타임 대조가 단독으로 맡습니다. 현재 Spring은 embeddingProfile을 아직 다루지 않아(back 전수 검색 0건) 실질 이중화가 없지만, -135에서 붙을 때 Spring이 값을 어디서 얻을지가 남습니다. 지금 정하지 않은 것이 이 PR의 판단입니다 — 소비자 없이 정하면 붙일 때 뒤집힙니다. 이 유예에 이견이 있으면 짚어 주십시오.
2. 덮어쓰기가 상시화되면 전제가 깨집니다. 배포가 늘 환경변수로 덮어쓴다면 그 값은 공개가 아니라 환경 종속이므로 분류를 다시 봐야 합니다. 그 경우 알려 주십시오.

절차에 대해

이 PR은 원래 ai 레포 변경과 함께 갔어야 했습니다. 처음에 ai/docs/spec/model-profile.md(하위 명세)만 고치고 이 문서를 그대로 뒀는데, CONTRIBUTING.md가 *"공용 계약과 충돌하면 소유 파트와 합의한 뒤 양쪽 문서를 갱신한다"*고 요구합니다. 하위 명세만 고치면 두 문서가 어긋난 채 남습니다. 발견하고 되돌려 이 PR을 먼저 올립니다.

미결 / 후속

• Spring 쪽 Profile 취득 경로 — -135 검색 연동에서 결정
• ai 레포 구현 PR — 이 PR 머지 후 올립니다(config.py 기본값 · .env.example 공개/비밀 분리 · 봉인 대상 축소 · P45)

🤖 Generated with Claude Code