Skip to content

README.ko.md

Latest commit

 

History

History
468 lines (335 loc) · 18.5 KB

README.ko.md

File metadata and controls

468 lines (335 loc) · 18.5 KB

OpenResearch banner

🔬 OpenResearch

탐색 · 평가 · 진화

AlphaEvolve 스타일의 연구·엔지니어링 반복을 위한 미션 기반 자율 최적화 런타임.

🇺🇸 English · 🇨🇳 中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇪🇸 Español · 🇫🇷 Français

Python Runtime Search Status

OpenResearch는 반복적 연구·엔지니어링 루프를 위한 로컬 자율 최적화 런타임입니다.

목표를 정의하고, 편집 가능한 표면을 제한하고, 제한된 실험을 실행하고, 결과를 점수화하고, 재생 가능한 상태 기록을 남길 수 있습니다. 하나의 저장소에서 일반 mission-driven runtime과 기존 단일 GPU train.py 개선 루프를 함께 지원합니다.

영어 ../../README.md가 현재 기준 문서입니다. 더 깊은 기술 문서도 주로 영어로 제공됩니다. 이 페이지는 가능한 한 영어 README와 구조를 맞춥니다.

🌐 언어 버전

로컬라이즈된 개요 페이지를 원하면 다음 독립 문서를 보세요.

  • ../../README.md
  • ./README.zh-CN.md
  • ./README.ja.md
  • ./README.es.md
  • ./README.fr.md

✨ 핵심 특징

  • 하나의 저장소, 두 개의 표면: 일반 openresearch runtime과 기존 OpenResearch Legacy
  • 목표 중심 반복: candidate surface, evaluator, budget, optimization goal 정의
  • 메모리를 가진 검색: .openresearch/ 아래 round history, frontier, artifacts, reports 저장
  • 다양한 작업군: benchmark, prompt, offline eval, repo patch, artifact transform, 실제 GPU 검색
  • 검사 가능한 출력: inspect, replay, HTML visualize 지원
  • 릴리스급 검증: smoke gate와 real hard gate 포함

🚀 왜 OpenResearch인가

  • Mission-driven runtime: 일회성 스크립트 대신 JSON mission으로 작업 정의
  • AlphaEvolve 스타일 검색: 변경 제안, 실험 실행, 결과 평가, 최적 frontier 활용
  • 재현 가능한 출력: .openresearch/ 아래 state, artifacts, reports, proposal journals 저장
  • 다중 adapter 계열: command benchmark, offline eval, prompt eval, repo patch eval, artifact transform, 실제 train.py 검색
  • 실제 릴리스 검증 경로: smoke / hard gate 스크립트 포함

🆚 OpenResearch와 AutoResearch 비교

차원 AutoResearch OpenResearch 업그레이드
프로젝트 형태 train.py 개선 루프 중심의 단일 경로 저장소 OpenResearch Legacy + 일반 openresearch runtime의 이중 표면 시스템 기존 경로를 유지하면서 더 넓은 runtime / platform으로 확장
주요 입력 program.md, prepare.py, train.py, 직접 편집 일반 runtime은 mission JSON, legacy 경로는 train.py 유지 기존 흐름을 지우지 않고 구조화 입력 추가
수정 표면 주로 train.py 한 지점 mission의 editable_paths, 여러 adapter, 실제 train.py 루프 유지 고정 단일 지점에서 구성 가능한 검색 표면으로 확장
실행 모델 짧은 훈련을 반복하는 단일 워크플로 mission run, mission orchestrate, mission search 하나의 루프를 재사용 가능한 execution/search runtime으로 확장
검색 행동 모델 훈련 중심 keep-or-discard bootstrap, exploit_best, diversify, parent refinement 더 명시적인 AlphaEvolve 스타일 search policy
검색 메모리 주로 로그와 결과표 policy_state, population_entries, frontier_entries, search_history 저장 durable frontier / population 상태 추가
Proposal 추적 일반 proposal journal 표면 없음 proposal_journal.jsonl, selected-target context, replayable round records proposal lineage와 target history 가시화
리포트 / 시각화 수동 로그 확인 중심 mission inspect와 mission visualize 공유 가능한 진단 / 보고 표면 추가
확장성 원래 훈련 도메인 중심 benchmark, prompt eval, offline eval, repo patch eval, artifact transform, 실제 openresearch 단일 루프에서 일반 최적화 runtime으로 확장
릴리스 검증 수동 / 경험 중심 packaged smoke gate와 real hard gate 더 명시적인 release-grade validation

요약하면, OpenResearch는 기존 AutoResearch를 유지하면서도 플랫폼화와 AlphaEvolve 스타일 검색을 강화한 형태입니다.

🧬 AlphaEvolve 스타일 업그레이드

  • 외부 검색 진행: bootstrap에서 exploit_best로 진행되며, bootstrap-only 검색 이력은 gate에서 실패 처리
  • Frontier / population memory: 로그만이 아니라 frontier candidates, population entries, search history를 저장
  • Target-aware exploitation: refine_parent가 이전 proposal 기록을 활용해 target을 조정
  • Cooldown: 최근에 성과가 없거나 과도하게 사용된 target을 일시적으로 식힘
  • Step shrinking: 같은 target에서 회귀가 반복되면 다음 제안의 step을 줄임
  • Replay / inspect: proposal journal, saved state, HTML report로 검색 과정을 감사 가능

이것은 OpenResearch가 AlphaEvolve 그 자체라는 뜻이 아닙니다. 핵심은 원래의 단일 AutoResearch 루프보다 더 재사용 가능한 AlphaEvolve 스타일 로컬 검색 runtime에 가까워졌다는 점입니다.

🎯 어떤 작업을 실행할 수 있나

OpenResearch는 다음이 있을 때 잘 맞습니다.

  • 수정하거나 생성할 수 있는 candidate surface
  • 수치 지표를 산출하는 evaluator
  • 후보의 우열을 판단할 수 있는 bounded loop

현재 예시:

  • command-driven benchmark 개선
  • prompts / rubric-driven evaluation 반복
  • offline evaluation harness 실행
  • replay 가능한 artifacts를 포함한 repo-local patch 평가
  • artifact transformation 후보 생성 루프
  • GPU에서 실제 OpenResearch train.py 검색 실행

🧭 사용 사례

적합한 경우:

  • one-shot prompting 대신 지표 중심 반복 개선을 원할 때
  • prompts, configs, 작은 editable repo surface를 최적화할 때
  • patch-evaluate-decide 루프와 artifact trail을 함께 남기고 싶을 때
  • 고정 harness / benchmark 위에서 후보를 비교할 때
  • 실제 훈련 워크로드에서 AlphaEvolve 스타일 로컬 검색을 시도할 때

부적합한 경우:

  • 실행 가능한 evaluator가 없을 때
  • 성공 조건을 metric이나 명시적 규칙으로 표현할 수 없을 때
  • editable surface가 너무 넓어서 bounded iteration 의미가 약해질 때

⚡ 30초 퀵스타트

요구 사항:

  • Python >=3.10
  • uv
  • 실제 openresearch 훈련 검색에는 NVIDIA GPU 필요

의존성 설치:

uv sync

가장 안전한 엔드투엔드 예시:

uv run openresearch mission orchestrate examples/missions/command-benchmark-basic.json
uv run openresearch mission inspect examples/missions/command-benchmark-basic.json
uv run openresearch mission visualize examples/missions/command-benchmark-basic.json

얻을 수 있는 것:

  • .openresearch/ 아래 저장 상태
  • mission workspace 아래 artifacts
  • reports/command-benchmark-basic.html 같은 HTML 보고서

🧱 두 가지 제품 표면

1️⃣ openresearch Runtime

일반 mission-driven runtime이 필요할 때:

  • mission run
  • mission orchestrate
  • mission search
  • mission inspect
  • mission validate
  • mission visualize

주요 경로:

  • ../openresearch/README.md
  • ../../packages/openresearch
  • ../../examples/missions/
  • ../../scripts/release/generic_v1_smoke.sh
  • ../../scripts/release/openresearch_real_run_gate.sh

2️⃣ OpenResearch Legacy

원래 단일 GPU 루프를 쓰고 싶을 때:

  • 데이터 준비
  • train.py 편집
  • 짧은 훈련 실행
  • val_bpb 비교
  • keep / discard 결정

주요 경로:

  • ../../apps/prepare.py
  • ../../apps/train.py
  • ../../apps/program.md
  • ../../packages/openresearch_legacy
  • ../openresearch-legacy/README.md
  • ../../examples/legacy/README.md

📝 Mission 입력

openresearch의 주요 입력은 mission JSON 파일입니다.

최소 형태:

{
  "id": "command-benchmark-basic",
  "adapter": {
    "kind": "command_benchmark"
  },
  "workspace": {
    "repo_root": ".",
    "editable_paths": ["prompts/**", "configs/**"]
  },
  "evaluation": {
    "primary_metric": "score",
    "goal": "maximize"
  },
  "budget": {
    "max_iterations": 3
  }
}

예시 파일:

  • ../../examples/missions/command-benchmark-basic.json
  • ../../examples/missions/offline-eval-harness-basic.json
  • ../../examples/missions/prompt-eval-harness-basic.json
  • ../../examples/missions/repo-patch-eval-harness-basic.json
  • ../../examples/missions/artifact-transform-harness-basic.json
  • ../../examples/missions/openresearch-openai-compatible.json
  • ../../examples/missions/template-basic.json

🛠️ 자주 쓰는 실행 경로

🟢 안전한 Mission Runtime

uv run openresearch mission orchestrate examples/missions/command-benchmark-basic.json
uv run openresearch mission search examples/missions/command-benchmark-basic.json
uv run openresearch mission inspect examples/missions/command-benchmark-basic.json
uv run openresearch mission visualize examples/missions/command-benchmark-basic.json

🧪 Legacy 단일 GPU 워크플로

uv run openresearch-prepare
uv run openresearch-train

호환 엔트리:

  • uv run python apps/prepare.py
  • uv run python apps/train.py
  • 루트의 prepare.py, train.py, attention_kernel.py, program.md

🔥 실제 OpenResearch 검색

전제 조건:

  • NVIDIA GPU
  • uv sync
  • uv run openresearch-prepare
  • 다음 환경 변수를 export:
    • OPENRESEARCH_LLM_BASE_URL
    • OPENRESEARCH_LLM_API_KEY

실행:

uv run openresearch mission search examples/missions/openresearch-openai-compatible.json --fresh

릴리스급 검증:

OPENRESEARCH_LLM_BASE_URL="$OPENAI_BASE_URL" \
OPENRESEARCH_LLM_API_KEY="$OPENAI_API_KEY" \
./scripts/release/openresearch_real_run_gate.sh examples/missions/openresearch-openai-compatible.json

📦 얻는 결과물

대표 출력:

  • .openresearch/<mission>.json 아래 저장된 mission state
  • artifacts/ 아래 replay 가능한 artifacts
  • reports/ 아래 HTML 보고서
  • proposal_journal.jsonl 같은 proposal history
  • legacy 경로의 run.log 및 results.tsv

저장소에 포함된 예시:

  • ../../release_examples/command-benchmark-search/reports/command-benchmark-basic.html
  • ../../release_examples/repo-patch-eval/reports/repo-patch-eval-harness-basic.html
  • ../../release_examples/openresearch-real/openresearch-openai-compatible.html
  • ../../release_examples/openresearch-real/gate.log

🔄 동작 방식

flowchart TD
    A[User goal] --> B[Mission JSON]
    B --> C[Adapter kind]
    C --> D[mission run / orchestrate / search]
    D --> E[Generate candidate]
    E --> F[Execute experiment]
    F --> G[Evaluate metric]
    G --> H{Keep or discard?}
    H -->|keep| I[Persist state and artifacts]
    H -->|discard| I
    I --> J[Inspect / Replay / Visualize]
Loading

실제 openresearch adapter에서는 AlphaEvolve 스타일 동작이 외부 search loop에서 나타납니다.

  • LLM-backed roles가 train.py 변경을 제안
  • runtime이 제한된 훈련 실험을 실행
  • val_bpb와 runtime 지표를 기록
  • search policy가 여러 round에 걸쳐 최적 frontier를 활용
  • accepted history를 저장하고 replay / inspect 가능

🧩 내장 Adapter 계열

Adapter 대표 candidate 대표 primary metric 대표 output
openresearch train.py patch val_bpb results table, run log, proposal journal
command_benchmark command/config change score, latency_ms benchmark metrics, run log
offline_eval_harness eval candidate score, pass_rate eval summary, predictions
prompt_eval_harness prompt/rubric change score, pass_rate summary, outputs
repo_patch_eval_harness repo-local patch 작업 정의 metric summary, diff artifact
artifact_transform_harness transformed artifact 작업 정의 metric transformed files, summary
template adapter scaffold candidate mission 정의 metric starter output surface

✅ 검증 상태

현재 검증된 스냅샷:

  • ../openresearch/release-notes-milestone1-v1.md
  • ../openresearch/release-validation.md

검증 증거:

  • 437 테스트 통과
  • packaged smoke gate 통과
  • real hard gate 통과, 3 rounds 및 숫자형 best_val_bpb 확인

📌 프로젝트 상태

  • 현재 milestone: milestone1 / complete version V1
  • 안정 사용자 표면: openresearch runtime 및 OpenResearch Legacy
  • 검증 완료 경로: mission runtime, inspect/visualize, packaged smoke gate, real openresearch hard gate
  • 실제 검색의 하드 요구 사항: NVIDIA GPU + OpenAI-compatible provider credentials
  • 현재 경계: 이전 이름 CLI shim 없음, formal citation metadata 없음, package 수준의 표준화된 license metadata도 아직 정리 중

🛣️ 로드맵

현재 코드베이스와 가장 맞닿아 있는 단기 개선 방향:

  • public packaging 및 repo metadata 강화
  • formal citation metadata 추가 및 packaging / provenance metadata 정리
  • public-facing release examples 및 visualization assets 확장
  • generic adapter ergonomics 및 validation surface 개선
  • contributor workflow 및 release docs 정리

❓ FAQ

🧱 openresearch와 OpenResearch Legacy의 차이는?

openresearch는 일반 mission-driven runtime입니다. OpenResearch Legacy는 데이터 준비, train.py 수정, val_bpb 비교를 중심으로 한 원래의 단일 GPU 워크플로입니다.

🖥️ GPU가 꼭 필요한가요?

대부분의 예제는 필요 없습니다. command benchmark, offline eval, prompt eval, repo patch eval, artifact transform은 실제 GPU 훈련 경로 없이 사용할 수 있습니다. 실제 openresearch 훈련 검색만 GPU가 필요합니다.

📝 주요 사용자 입력은 무엇인가요?

일반 runtime에서는 examples/missions/ 아래의 mission JSON 또는 동일 형태의 mission spec이 주요 입력입니다. legacy 경로에서는 실질적인 작업 표면이 train.py와 apps/program.md입니다.

🎯 어떤 작업에 적합한가요?

제한된 editable surface, 실행 가능한 evaluator, 후보의 우열을 판단할 metric이 있는 작업에 가장 잘 맞습니다.

🧬 이게 AlphaEvolve 그 자체인가요?

아닙니다. OpenResearch는 AlphaEvolve 스타일의 로컬 검색 runtime입니다. 변경 제안, 제한된 실험, 결과 평가, 라운드 간 반복을 수행하지만 어떤 proprietary internal system의 문자 그대로의 복제는 아닙니다.

📚 인용

현재 저장소에는 정식 CITATION.cff 또는 논문 공개가 없습니다.

지금 인용해야 한다면 다음과 같은 software-style reference를 사용할 수 있습니다:

OpenResearch contributors. OpenResearch: a local autonomous optimization runtime
for iterative research and engineering loops. Software, 2026.

나중에 canonical public repository URL, 논문, citation metadata가 공개되면 이 섹션을 그 권위 있는 출처로 업데이트해야 합니다.

⚖️ 라이선스

이 저장소는 이제 루트 LICENSE 파일을 포함합니다.

중요한 범위 설명:

  • LICENSE는 이 저장소 안에서 OpenResearch contributors가 작성한 OpenResearch 고유 기여분에 적용됩니다
  • 제3자 자료나 upstream 유래 파생물에 대해 추가 권리를 부여하지 않습니다
  • OpenResearch는 Andrej Karpathy의 upstream AutoResearch 프로젝트를 기반으로 확장되었습니다
  • 2026년 3월 19일 기준으로 upstream AutoResearch 저장소 페이지에는 정식 LICENSE 파일이 보이지 않았으므로, upstream 유래 부분을 재사용할 때는 upstream 권리를 별도로 검토해야 합니다

추후 upstream 라이선스 조건이 공개되거나 명확해지면, 이 LICENSE와 본 섹션도 함께 갱신해야 합니다.

🙏 감사의 말

OpenResearch를 가능하게 한 upstream 오픈소스 프로젝트에 명시적으로 감사를 전합니다.

OpenResearch는 원래의 단일 GPU 루프를 OpenResearch Legacy로 보존하면서, 그 계보를 더 넓은 mission-driven runtime, replay 가능한 평가 표면, AlphaEvolve 스타일 로컬 검색으로 확장합니다.

🤝 기여

기여하려면:

  • ../user-quickstart.md 와 ../openresearch/README.md 부터 시작
  • 가능하면 변경 범위를 하나의 surface로 제한: openresearch runtime 또는 OpenResearch Legacy
  • public operator path를 변경했다면 stable docs도 함께 갱신

최소 검증:

uv run pytest -q
./scripts/release/generic_v1_smoke.sh

runtime/docs-only 변경이라면 반복 중에는 다음 정도로도 충분할 때가 많습니다:

uv run pytest tests/integration/test_docs_navigation.py -q
git diff --check

🗂️ 문서

먼저 볼 것:

  • ../../README.md
  • ../user-quickstart.md
  • ../openresearch/README.md
  • ../openresearch/quickstart.md
  • ../openresearch/mission-runtime.md

Runtime 문서:

  • ../openresearch/adapter-authoring.md
  • ../openresearch/replay-and-inspect.md
  • ../openresearch/release-validation.md
  • ../openresearch/troubleshooting.md

Legacy 문서:

  • ../openresearch-legacy/README.md
  • ../openresearch-legacy/operator-guide.md
  • ../openresearch-legacy/setup-and-data.md
  • ../openresearch-legacy/troubleshooting.md

기록 아카이브:

  • ../plans/README.md