[AI] AI–Backend 통신 방향과 callback 미사용 계약 확인

[tpals0409]

확인하려는 내용

현재 AI–Backend 연동을 아래와 같이 이해하고 있습니다.

Backend ── 내부 API 요청 ──> AI
Backend <── 같은 HTTP 요청의 응답 ── AI

즉, Backend가 AI API를 호출하고 AI는 해당 요청에 응답하지만, AI가 별도의 새 HTTP 요청을 만들어 Backend API를 호출하는 callback/webhook 방식은 사용하지 않는 구조로 이해했습니다.

이 관점이 현재 구현과 MVP 운영 방향에도 맞는지 확인 부탁드립니다.

현재 문서에서 확인한 근거

공용 정본인 static/05_AI_설계.md에는 다음 내용이 있습니다.

• Client의 요청은 Spring Backend를 거쳐 FastAPI AI Server로 전달됩니다.
• POST /internal/v1/context/process는 202 Accepted로 접수됩니다.
• AI 처리 완료 통보를 위한 webhook이나 polling 계약은 두지 않습니다.
• Spring은 영속화된 AI State를 직접 조회하여 처리 상태를 판단합니다.
• FastAPI는 core.*를 직접 조회하거나 수정하지 않습니다.

AI 저장소의 docs/spec/architecture.md에도 다음과 같은 책임 방향이 표현되어 있습니다.

Client → Spring Backend → FastAPI AI

현재 Kubernetes NetworkPolicy 역시 Backend Pod에서 AI의 8000 포트로 향하는 통신만 허용하고 있습니다.

확인 요청

아래 이해가 맞는지 확인 부탁드립니다.

1. AI API 호출의 시작 주체는 항상 Backend입니다.
2. AI의 동기 응답은 Backend가 시작한 기존 HTTP 연결을 통해 반환됩니다.
3. 비동기 Context 처리 완료 여부는 callback 없이 AI State를 통해 확인합니다.
4. AI가 Backend로 새 HTTP 요청을 시작하는 callback/webhook endpoint는 MVP 계약에 없습니다.
5. 따라서 AI → Backend 방향의 별도 NetworkPolicy나 인증 계약도 현재는 필요하지 않습니다.

함께 확인하고 싶은 예외

현재 또는 예정된 기능 중 아래와 같은 역방향 호출이 필요한 경우가 있는지도 확인 부탁드립니다.

• AI 처리 완료 알림
• 실패 즉시 통보
• 장시간 작업의 진행 상태 전달
• Backend의 재처리를 유도하는 callback
• 향후 챗봇·GraphRAG 기능에서의 Backend 역호출

예외가 없다면 현재의 단방향 호출 모델을 공용 문서와 AI 저장소 문서에 명시적으로 고정하면, 운영·테스트 과정에서 “AI → Backend도 열어야 하는가?”라는 혼동을 줄일 수 있을 것 같습니다.

기대 결과

• 현재 단방향 통신 관점이 맞는지 AI 담당자의 확인
• 예외적인 역방향 callback 계획이 있다면 endpoint·인증·재시도·멱등성 계약 정의
• 예외가 없다면 문서에 “AI는 Backend를 역호출하지 않는다”는 문구 보강

[colosair]

다섯 항목 전부 맞습니다 — 구현·계약 양쪽으로 확인했습니다

#	확인 요청	판정
1	AI API 호출의 시작 주체는 항상 Backend	맞다
2	동기 응답은 Backend 가 시작한 기존 HTTP 연결로 반환	맞다
3	비동기 완료 여부는 callback 없이 AI State 로 확인	맞다
4	AI → Backend callback/webhook endpoint 는 MVP 계약에 없다	맞다
5	따라서 AI → Backend 방향 NetworkPolicy·인증이 불필요하다	맞다 (단서 하나, 아래)

코드로도 확인했습니다

문서 근거는 인용해 주신 것으로 충분하고, 구현이 그것과 일치하는지 저희가 확인한 결과를 더합니다.

ai/app 전체에서 Backend 를 호출하는 코드가 0건입니다. 나가는 HTTP 는 GMS 게이트웨이 하나뿐입니다.

ai 가 접근하는 DB 스키마
  ai.context_ai_state · ai.context_embedding · ai.context_keyword
  ai.context_keyword_analysis · ai.keyword_preset

core.* 는 하나도 없습니다. 즉 HTTP 로도 DB 로도 Backend 쪽으로 가는 경로가 없습니다.

결과 전달 경로

back → ai   POST /internal/v1/context/process   202 = 접수만
            POST /internal/v1/search            동기 응답
ai  → DB    ai.* 에 임베딩·키워드·상태를 직접 쓴다
back → DB   ai.context_ai_state 를 읽어 판단한다

AI 는 Backend 에 아무것도 알리지 않습니다. Backend 가 상태 테이블을 읽거나 재스캔 스케줄러(back#104)가 5분 주기로 확인합니다.

확인하실 방향

필요    Backend Pod → AI Service (ClusterIP 8000)
        AI Pod → PostgreSQL (ai 스키마)
        AI Pod → GMS 게이트웨이 (외부)
불필요  AI Pod → Backend Pod

ingress.enabled: false 이므로 외부 진입점이 없는 것도 정상입니다.

단서 — 5번에만 붙습니다

Team-PinLog/back#129 에서 완료 이벤트를 역방향으로 보내는 안(안 B) 이 논의 중입니다. 지금은 MVP 계약에 없는 것이 맞고 저희도 그렇게 답했습니다. 다만 그 논의가 채택되면 5번이 바뀝니다.

저희는 그 이슈에서 "발행 자체는 부담스럽지 않으나 시점은 운영 배포 사슬이 풀린 뒤" 로 답했습니다. 당장 NetworkPolicy 를 여실 필요는 없고, 채택되면 그때 요청드리겠습니다.

문서 반영

이 확인 내용은 static/05_AI_설계.md 가 이미 담고 있어 개정이 필요하지 않습니다. 다만 "AI → Backend 방향 통신이 존재하지 않는다" 가 한 문장으로 모여 있지 않고 여러 절에 흩어져 있어, 이번처럼 인프라가 판단할 때 근거를 모아야 합니다.

한 줄로 명시하는 편이 나을지 의견 주시면 저희가 개정 PR 을 내겠습니다 — 공용 계약이라 저희 단독으로 고치지 않습니다.

[colosair]

소실 대비 — 큐 역할을 브로커가 아니라 DB 가 합니다

우려하신 지점이 정확합니다. "요청을 보내고 응답만 받고 끝" 이면 중간에 무엇이 죽어도 알 방법이 없습니다. 그래서 이 구조는 요청 전달과 상태 보존을 분리했습니다.

Record 저장 트랜잭션 안에서   ai.context_ai_state 에 PENDING 을 기록하고 커밋한다
커밋이 끝난 뒤              별도 스레드가 FastAPI 를 호출한다 (실패는 삼킨다)

호출이 실패하든, 큐에서 버려지든, FastAPI 가 죽든 PENDING 행은 이미 DB 에 있습니다. 그것이 이 설계에서 「소실되지 않는다」의 근거입니다.

이미 걸려 있는 복구 장치

장치	동작	근거
재스캔 스케줄러	5분 주기로 만료된 PENDING 을 다시 요청	back#104
PROCESSING 만료	10분 넘게 붙잡힌 작업을 재선점	같은 곳
FOR UPDATE SKIP LOCKED	인스턴스가 여럿이어도 같은 행을 두 번 집지 않음	같은 곳
retry_count 상한 3	3회 소진 시 FAILED 로 종결한다	스키마 CHECK 제약
재선점 로그	재선점이 일어나면 WARNING 한 줄	ai#64(오늘 병합)

즉 AI 가 처리 중 죽어도 최대 10분 뒤 다른 시도가 그 작업을 가져갑니다. 3회까지 그러고도 안 되면 FAILED 로 끝내 「영원히 PENDING」 상태가 남지 않게 합니다.

정직하게 — 남는 취약 지점 셋

대비가 완전하다는 뜻은 아닙니다. 우려하신 관점에서 실제로 약한 곳을 적습니다.

1. 복구가 즉시가 아니라 최대 5~10분 지연입니다

유실은 없지만 그 사이 사용자에게는 「처리 중」으로 보입니다. 시연처럼 짧은 시간에 결과를 보여야 하는 상황에서는 이것이 실질적인 문제입니다.

2. FAILED 종결 후에는 자동 복구가 없습니다

3회를 소진하면 그것으로 끝이고 사람이 봐야 합니다. 그런데 그것을 볼 수단이 방금 생겼습니다 — 오늘 ai#64 로 GMS 호출 실패율과 재선점을 로그에 남기게 했고, /metrics 는 infra docs/ai-serving.md 검증 순서 7 이 prod 승격 전 별도 승인으로 이관해 둔 상태입니다.

3. 커밋 후 호출이 쓰는 인메모리 큐는 포화되면 요청을 버립니다

aiCallExecutor   core 2 · max 4 · queueCapacity 100 · 차면 버린다

버려도 DB 상태가 남아 재스캔이 줍지만, 즉시 시도할 기회 하나를 잃습니다. 정상 부하(초당 약 1건)에서는 포화가 나지 않고, GMS 가 느려져 건당 수십 초가 되면 가능해집니다.

제안하신 「AI 가 처리 후 다시 보내주는 방식」

같은 제안이 Team-PinLog/back#129 의 「안 B」로 이미 열려 있습니다. 백엔드가 먼저 제기했고 인프라도 배정돼 있습니다.

그쪽에 저희 의견을 적었는데 요지는 이렇습니다.

발행 자체는 부담스럽지 않다        FastAPI 에 이벤트 발행을 넣는 것은 어렵지 않다
개선되는 것은 「지연」이다          유실 방지는 이미 DB 상태가 하고 있다
MQ 여야 하는지는 별도 판단          callback HTTP 로도 같은 통보가 된다
시점은 운영 배포 사슬이 풀린 뒤     양 파트 구현이 걸린다

논의가 세 곳으로 갈리면 결론이 흩어지므로 back#129 로 모으시는 편이 좋겠습니다. 이 이슈(통신 방향·callback 미사용 계약)는 「현재 계약이 무엇인가」 를, back#129 는 「그것을 바꿀 것인가」 를 다루는 것으로 나누면 깔끔합니다.

현재 계약 확인은 그대로 유효합니다

앞선 답변의 다섯 항목은 지금 시점의 사실이고, back#129 가 채택되면 4·5번이 바뀝니다. NetworkPolicy 는 지금 구성대로 두시면 되고, 채택 시 저희가 요청드리겠습니다.