jangminseok.com

핵심 기능

포트폴리오에 질문하는 AI 챗봇

화면 아래 입력창에 질문하면 AI가 제 프로젝트 문서를 찾아 답합니다. 답 끝에는 근거가 된 프로젝트 페이지 링크가 붙습니다. 포트폴리오에 없는 질문에는 답하지 않습니다.

핵심 기능

어떤 도구를 불렀는지 공개

답변마다 AI가 어떤 도구를 어떤 값으로 불렀는지 펼쳐 볼 수 있습니다. 문서 검색, 프로젝트 조회, 기술별 프로젝트 찾기 도구 3개를 상황에 맞게 골라 씁니다.

• 

  다른 AI 앱에서 쓰는 MCP 서버

  Claude 앱의 커넥터에 주소 하나(https://api.jangminseok.com/mcp/)를 등록하면, 그 앱의 AI가 같은 도구 3개로 제 포트폴리오를 조회할 수 있습니다.

• 

  프로젝트 소개 페이지

  프로젝트마다 무엇을 만들었는지, 주요 기능, 전체 구조, 맡은 일, 어려웠던 점을 한 페이지에서 읽을 수 있습니다. 각 프로젝트는 callguard.jangminseok.com처럼 자기 주소를 가집니다.

• 

  채용 요건별 근거 카드

  채용 공고에서 자주 보는 요건마다, 그 경험을 보여 주는 프로젝트 페이지로 바로 이어지는 카드를 모았습니다.

화면은 Next.js로, 챗봇과 MCP 서버는 FastAPI 하나로 만들었습니다. 두 입구가 같은 도구 코드를 불러서, 한쪽만 고쳐지는 일이 없습니다.

화면

Next.js 16React 19TypeScriptTailwind CSS

서버

Python 3.13FastAPISQLAlchemy 2import-linter

검색과 AI

PostgreSQL + pgvectorpg_trgmGeminiMCP

배포

VercelSupabaseGitHub Actions

1인 프로젝트입니다. 설계 문서를 먼저 쓰고, 그 문서에서 나눈 작업 단위대로 테스트부터 작성하며 만들었습니다.

1. 1.무료 AI 한도가 하루 20번뿐이던 문제

   문제

   처음 고른 Gemini 모델은 무료로 하루 20번만 부를 수 있었습니다. 질문 하나에 AI를 2~4번 부르기 때문에 하루에 받을 수 있는 질문이 5~10개뿐이었습니다.

   해결

   무료 한도 표를 비교해 하루 500번까지 쓸 수 있는 경량 모델(Gemini 3.5 Flash Lite)로 바꿨습니다. 바꾸기 전에 이 모델도 도구를 제대로 고르는지 먼저 시험했습니다.

   결과

   하루에 받을 수 있는 질문이 약 125~250개로 늘었습니다. 질문 하나에 2~4번 부른다고 보고 계산한 값입니다. 대신 경량 모델이라 조회한 사실을 답에서 빠뜨리는 경우가 남았고, 평가에서 그대로 드러납니다.

2. 2.두 번째 도구 호출부터 AI가 오류를 내던 문제

   문제

   로컬에서 챗봇을 처음 돌렸을 때, AI가 도구를 한 번 부른 뒤 다음 요청에서 400 오류가 났습니다.

   원인

   Gemini 3 계열은 도구를 부를 때 서명 값을 함께 주고, 다음 요청에서 그 서명을 그대로 돌려받아야 합니다. 설계 단계에서 이 조건을 몰랐습니다.

   해결

   대화 기록에 서명을 담아 다음 요청 때 돌려주도록 고쳤습니다. 이 동작을 확인하는 테스트를 먼저 쓰고 고쳤습니다.

   결과

   도구를 여러 번 이어서 부르는 질문도 정상으로 답합니다.

   코드로 확인Gemini 연결 코드 (gemini_llm.py) ↗

3. 3.평가로 찾아낸 챗봇 결함 두 가지

   문제

   시험 문제 30개로 처음 채점했을 때 도구 선택 정확도가 0.533이었습니다.

   원인

   문항별로 다시 돌려 보니 두 가지였습니다. AI가 프로젝트 이름을 짐작해 없는 값(localhost-daegu 등)을 넣고 있었고, 도구를 3번 부른 뒤에는 모은 근거가 있어도 답하지 않고 거절했습니다.

   해결

   도구 설명에 실제 프로젝트 이름 목록을 넣어 짐작할 필요가 없게 했습니다. 도구 호출 한도에 닿으면 도구 없이 지금까지 모은 근거로만 답하게 했습니다. 채점 기준도 한 가지 바로잡았습니다. 필요한 도구에 하나를 더 불러 맞게 답한 경우까지 틀렸다고 세고 있었습니다.

   결과

   도구 선택 정확도가 0.867, 답변 근거 적중률이 0.962가 되었습니다. 남은 오답도 문항별로 기록해 두었습니다.

   코드로 확인시험 문제 30개 (golden.yaml) ↗평가 결과 (eval.json) ↗

4. 4.키워드 검색 방식을 측정해서 고르기

   문제

   한국어 키워드 검색에는 전용 방식(PGroonga)이 더 좋다고 알려져 있어, 처음 쓴 방식(pg_trgm)을 바꿔야 할지 정해야 했습니다.

   해결

   두 방식의 차이는 키워드 검색 부분뿐이라, AI 없이 검색만으로 같은 시험 문제 26개를 돌려 비교했습니다. 미리 "0.03 이상 높을 때만 바꾼다"는 기준을 정해 두었습니다.

   결과

   기존 방식이 0.846, 전용 방식이 0.808이라 바꾸지 않았습니다. 이후 프로젝트 소개 페이지를 새로 쓰고 다시 재니 두 방식 모두 0.923으로 같아 그대로 두었습니다. 문항 수가 적어 차이 자체를 확신하기는 어렵다는 점도 함께 기록했습니다.

   코드로 확인검색 비교 코드 (run.py) ↗