기술 작성을 위한 LLM: 가이드

저는 인정하고 싶지 않을 만큼 README를 다시 쓰는 데 많은 시간을 소비합니다. 이 가이드에서는 Oxlo.ai에 호스팅된 LLM을 사용하여 불렛 포인트(bullet points)와 거친 메모를 프로덕션 수준의 기술 문서로 변환하는 작은 CLI 도구를 어떻게 만들었는지 보여드리겠습니다. 이는 API 문서, 런북(runbooks) 또는 내부 위키(internal wikis)에 맞춰 조정할 수 있는 단일 Python 스크립트입니다.

필요한 사항

Python 3.10 이상
https://portal.oxlo.ai에서 발급받은 Oxlo.ai API 키
OpenAI SDK: pip install openai

1단계: Oxlo.ai 클라이언트 초기화

tech_writer.py라는 이름의 파일을 생성합니다. 저는 Llama 3.3 70B를 사용하는데, 그 이유는 이 모델이 긴 시스템 지침(system instructions)을 안정적으로 따르고 군더더기 없는 깔끔한 Markdown을 출력하기 때문입니다.

from openai import OpenAI
import os

...

2단계: 시스템 프롬프트(system prompt) 고정

이 프롬프트가 제품의 핵심입니다. 프롬프트는 말투, 구조, 형식을 제한하여 모델이 챗봇(chatbot)이 아닌 시니어 기술 작가(senior technical writer)처럼 행동하도록 만듭니다.

SYSTEM_PROMPT = """당신은 시니어 기술 작가입니다. 당신의 업무는 거친 엔지니어의 메모를 다듬어진 Markdown 문서로 변환하는 것입니다.

규칙:
...

3단계: 셀프 리뷰 루프(self-review loop) 추가

초안에는 항상 빈틈이 있기 마련입니다. 저는 비판(critique) 단계를 거친 후 수정(revision) 단계를 실행합니다. Oxlo.ai에서는 두 번의 추가 요청(requests) 비용이 발생하지만, 요청당 가격이 고정되어 있기 때문에 메모와 초안이 길어지더라도 비용을 예측할 수 있습니다. 정확한 요율은 Oxlo.ai 가격 페이지에서 확인할 수 있습니다.

def critique_and_revise(draft: str, original_notes: str) -> str:
    critique_prompt = f'''다음 기술 초안을 다음의 원본 메모와 대조하여 검토하십시오.

...

4단계: CLI 연결

텍스트 파일로부터 메모를 파이프(pipe)로 입력받을 수 있도록 인자 파싱(argument parsing)과 파일 I/O를 추가합니다.

import argparse

def main():
...

실행하기

거친 불렛 포인트가 담긴 notes.txt를 생성합니다:

새로운 인증 (auth) 서비스를 배포합니다. 세션 관리를 위해 Redis가 필요합니다. 환경 변수 (Env vars): AUTH_SECRET, REDIS_URL. Docker 빌드 컨텍스트 (build context)는 ./auth입니다. 포트 (Port) 8080. 헬스 체크 (Health check) 경로는 /health입니다. 메모리 제한 (memory limit)을 512mb로 설정하는 것을 잊지 마세요.

그 다음 스크립트를 실행합니다:

export OXLO_API_KEY=your_key_here
python tech_writer.py notes.txt -o auth_deploy.md

결과물인 auth_deploy.md는 다음과 같습니다:

# 인증 서비스 배포하기

이 가이드는 Redis 세션 저장소를 사용한 인증 서비스 배포를 다룹니다.
...
```bash
   docker build -t auth-service:latest ./auth

필요한 환경 변수 (environment variables)를 설정합니다:
```
export AUTH_SECRET=your_secret_here
export REDIS_URL=redis://host:6379
```
1
2
3

메모리 제한 및 포트 매핑 (port mapping)과 함께 컨테이너를 실행합니다:

docker run -d \
  --memory="512mb" \
  -p 8080:8080 \
  -e AUTH_SECRET \
  -e REDIS_URL \
  auth-service:latest

헬스 엔드포인트 (health endpoint)를 확인하여 배포를 검증합니다:
```
curl http://localhost:8080/health
```
1
2

문제 해결 (Troubleshooting)

...


## 마무리 및 다음 단계

이제 Oxlo.ai를 기반으로 작동하는 기술 작성 (technical writer) CLI를 갖게 되었습니다. 이를 확장할 수 있는 두 가지 구체적인 방법은 다음과 같습니다:

1. 최종 Markdown을 두 번째 Oxlo.ai 호출에 입력하여, 동일한 단일 요청 비용을 재사용하면서 일치하는 OpenAPI 명세 (OpenAPI spec) 또는 JSON 스키마 (JSON schema)를 생성합니다.
2. 컨텍스트 (context)가 수만 토큰을 초과하는 런북 (runbooks)의 경우, 모델을 Kimi K2.6으로 교체합니다. Oxlo.ai는 동일한 요청당 요율로 131K 컨텍스트 윈도우 (context window)를 처리하며, 이는 대규모 마이그레이션 가이드나 아키텍처 결정 기록 (architecture decision records)에 유용합니다.

Insights

기술 작성을 위한 LLM: 가이드

요약

핵심 포인트