오리의 대학원 준비일지

Zotero + Obsidian 사용해서 논문 읽는 방법

orieasy1 — Sun, 9 Aug 2026 09:24:09 +0900

Zotero 하이라이트 Obsidian으로 가져오는 방법

Zotero & Obsidian 사용법

안녕하세요, 이번엔 지난 포스팅에 이어서 Obsidian과 Zotero를 활용해서 논문 읽는 방법을 마저 설명드리려 해요.

기본적인 Zotero 사용법과 기본설정, 논문 읽는 방법(공학계열)은 이전 포스팅을 참고해주세요!!

이전 포스팅 바로가기

⬇️⬇️

https://easy1nhard2.tistory.com/35

영국 방문연구원의 Zotero로 논문 읽는 방법!

️ 공학계열 논문 읽는법, Zotero 사용법 안녕하세요..?오랜만입니다.... 껄껄 저는 25년도 중반까지, 그리고 특히 24년에 개발자가 되겠다는 꿈을 안고,,최대한 부지런히 tech blog를 썼던 사람입니

easy1nhard2.tistory.com

위 포스팅과 아래 이미지에서 보실 수 있다시피 Zotero는 논문을 읽어 내려가면서 하이라이트를 바로 칠할 수 있고, 본인의 느낀 점을 comment로 바로바로 달 수 있다는 장점이 있습니다.

그래서 저는 개인적으로 LLM 의존도가 줄고, 영어 문장 구조를 파악하는 힘, 논문 독해 실력이 올라가는 느낌을 받았어요.

그러나 이렇게 comment가 길어질 경우에는 내용이 끊기고, comment가 많아지면 많아질수록 한눈에 파악하기 힘들어집니다.

그렇다면!!

내가 작성한 모든 comment를 한 번에! 가져와서 볼 수 있다면 정말 편리하겠죠?

그럴 때 사용할 수 있는 게 바로 Obsidian이라는 애플리케이션입니다!

Obsidian(옵시디언 설치 바로가기)

⬇️⬇️

https://obsidian.md/download

Download

Obsidian is available on all major platforms. Download Obsidian for iOS, Android, macOS, Windows and Linux.

obsidian.md

Obsidian은 차세대 Notion으로 각광받고 있는 서비스입니다.

무엇도 내가 작성한 노트들을 링크로 연결할 수 있어 문서들간의 관계성을 "시각화"할 수 있다는 것이 가장 큰 장점이죠.

Obsidian에서는 Zotero와 관련한 커뮤니티 플러그인을 지원하는데요, 해당 플러그인을 사용하여 내가 Zotero에서 작성한 메모들을 한꺼번에 불러들일 수 있습니다.

그럼 이제부터 저의 Zotero, Obsidian을 사용한 논문 읽기 방법을 본격적으로 소개해 드리도록 하겠습니다.

1. Obsidian(옵시디언) 시작하기

우선 Obsidian 설치를 완료하시고 보관선(볼트)까지 만들었다는 전제하에 시작하겠습니다.

(아래 영상의 해당 영상의 1:45까지)

Obsidian의 전반적인 세팅은 아래 영상을 참고해 주시면 좋을 것 같습니다!

기본적인 사용법을 잘 정리해 두셨더라고요. 개인적으로 도움을 많이 받은 영상이라서 추천드립니다.

https://youtu.be/ZuEu8SDqHOE?is=RU7V66ibiRnkx62f

그러면 여러분도 아래와 같은 화면을 보고 계실텐데요,

(전 이것 저것 플러그인을 설치한게 있어서 조금 다르긴 합니다만..)

그렇다면, 좌측 상단에 폴더 아이콘 안에 +가 있는 아이콘을 눌러서 논문들을 불러올 폴더를 하나 만들어주세요!

저는 '3. Papers'라고 이름 붙였습니다.

이제 플러그인 설치를 할 거예요.

옵시디언의 플러그인은 '코어 플러그인'과 '커뮤니티 플러그인'으로 나뉘는데요, 코어는 옵시디언에서 기본적으로 제공해주는 것들, 커뮤니티는 사람들이 편의를 위해 만들어낸 플러그인이라고 생각하시면 됩니다.

저희가 오늘 사용할 건 모두 '커뮤니티 플러그인'이에요!

Obsidian > Preferences > 커뮤니티 플러그인 > 탐색으로 들어가주겠습니다.

총 2개의 플러그인을 설치할껀데요,

1. Templater

2. Zotero Integration 입니다.

설치 버튼 눌러주시구요, 설치 후에는 활성화까지 눌러주시길 바랍니다.

(활성화 버튼 꼭 눌러주셔야해요!)

이후 Preferences(설정)창으로 돌아와서 좌측하단에 플러그인이 뜨는지 확인해주세요!

그리고 아래 사진처럼 설정해주세요!

Zotero와의 연결을 위해선 Templater 설정이 많이 필요하지 않습니다.

Zotero에 단 우리의 코멘트를 들고와서 어떻게 보여줄지를 설정하기 위한 플러그인이예요 :)

Zotero Integration 설정을 하기 전에 위에서 'Template folder location' 칸에 작성한 이름과 동일한 폴더를 하나 만들어주세요.

그리고 Zotero Template 이라는 파일을 하나 만들어줍니다

이제 다시 설정으로 돌아와서,

우선 본인이 설정한 논문들을 불러고오자 하는 폴더명 (저의 경우엔 3. Papers)를 아래 사진처럼 칸에 작성해주세요.

그리고 우측 사진처럼 포멧 설정을 이어서 해줘야하는데요.

Name: 우리가 하려는 동작(Zotero에서 내용 불러와서 Obsidian에 저장) 이름 (자유)
Output Path: 저장경로, 본인이 설정한 폴더 이름/@{{citekey}}.md 형식으로 설정해주세요
Image Output Path: 이미지 저장 경로, 본인이 설정한 폴더 이름/images/{{citekey}}/
Template File: 논문들을 불러올 때 적용할 템플릿: templates/Zotero Template.md
Bibliography Style: 인용스타일, 본인이 연구하는 분야의 형식으로 지정해주시면 됩니다! (저는 컴공이라 히히)

그럼 이제 옵시디언에서 필요한 기본 설정은 끝입니다!

2. Zotero 설정

Zotero에서 Obsidian으로 내용을 들고 올 때 필요한 citekey설정을 진행하겠습니다.

아래 플러그인을 다운받아주세요!

⬇️⬇️

https://retorque.re/zotero-better-bibtex/installation/index.html

Installation :: Better BibTeX for Zotero

Install by downloading the latest release – if you use Firefox, make sure to right-click and save the XPI file, not just clicking it – and then in Zotero: In the main menu go to Tools > Plugins Select ‘Plugins’ Click on the gear in the top-right co

retorque.re

latest release를 클릭하셔서 xpi 확장자 파일을 다운받아주세요.

그리고 지난 포스팅에서 했던 것과 동일한 방향으로

Zotero > Tools > Plugins에 들어가신 뒤, Install Plugins Form File > 다운받은 xpi 확장자 플러그인 파일 클릭!

해당 창을 닫고 Settings 창에 들어가셔서 citation key formula를 수정해 주셔도 되고 안 해 주셔도 됩니다.

제가 제공해드리는 템플릿을 사용하게 되면 이 citekey가 노트 제목으로 오게 되는데요,

저는 어떤 논문인지 제가 구분할 수 있어야하고 1저자 정도는 표시를 하는게 좋을 것 같다는 생각이 들어서

shorttitle(3,3) + "_" + auth + "_etal" 조합으로 설정해 두었습니다.

아까 설치했던 사이트에 가면 다른 Citation key formula도 있으니 한번 구경해보시고 마음에 드는 걸로 설정하셔도 좋을 것 같습니다.

⬇️⬇️

https://retorque.re/zotero-better-bibtex/citing/index.html

Citation Keys :: Better BibTeX for Zotero

Generating citekeys for your items The BibTeX citations keys generated by the standard Zotero exporters are always generated at time of export, using an algorithm that usually generates unique keys. For serious LaTeX users, “usually” presents the follo

retorque.re

그리고 바뀐 설정을 적용하기 위해 논문들을 모두 선택해서

우클릭 > Better BibTeX > Regenerate BibTeX key 를 클릭해 citekey를 다시 설정해 줍니다.

논문을 클릭하면 우측 내요에 논문 관련 정보들이 뜨게 되는데 Citation Key에서 우리가 적용한 설정이 잘 반영이 되었는지 확인해줍니다.

그럼 이제 모든 설정은 끝났어요!!

3. 이제 Template을 만들 차례

템플릿을 만들기 전에!

Zotero는 아래 8가지 색깔의 하이라이트를 형광펜과 밑줄 형태로 제공해요.

그리고 이전 포스팅에서 제가 언급한 논문을 읽을 때 생각해야 할, 얻어 가야 할 내용 5가지를 소개해 드렸죠?

저는 그 내용들과 색깔을 연결시켜요.

이 논문의 RQ와 Contribution
실험 설계 및 분석방법론
논문의 결과
논문의 한계
이 논문과 내 연구와의 관계성

이었는데요, 여기에 개인적으로 중요하다고 생각하는 내용을 추가해서!

읽을 때 총 6가지의 색상을 사용합니다.

색	Zotero 색 이름	용도	무엇을 칠하나	콜아웃
주황	Orange	RQ / 문제의식	이 논문이 답하려는 질문, 연구 목적, 풀려는 문제	question
파랑	Blue	Method	대상·표본, 실험 설계, 측정 지표, 절차	info
초록	Green	Result	실제 수치, 발견, 통계 결과	success
빨강	Red	Limitation	저자가 밝힌 한계, 내가 발견한 약점·반론	failure
⚪ 회색	Gray	내 연구와의 연결	내 연구에 써먹을 지점, 인용 후보, 아이디어	quote
노랑	Yellow	개인적으로 중요	그 외 개인적으로 중요하다고 생각한 부분	attention

표를 보고 콜아웃이 뭐지? 라고 생각하시는 분들이 있으실텐데요,

노션을 사용하시던 분들이라면 이미 알고 계시겠지만, 박스를 만들어서 안에 내용을 작성할 수 있는데 해당 형태를 '콜아웃'이라고 불러요.

이런 형식이 콜아웃!

Obsidian에서도 해당 기능을 지원하는데요, 지원하는 아이콘과 색깔은 다음과 같아요.

홈페이지 참고: https://obsidian.md/help/callouts

Callouts - Obsidian Help

This page details how to use callouts to include additional content without breaking the flow of your notes.

obsidian.md

저는 여기서 지원해 주는 색과 기호와 제가 Zotero에서 사용하는 색을 최대한 통일시켰어요.

그래서 하이라이트 내용을 불러오면 제가 형광펜 혹은 밑줄 쳤던 색과 같은 콜아웃 박스에 내용이 들어오게 되는 것이죠!

위 색과 내용을 여러분 취향대로 조합해 보셔도 좋을 것 같습니다!

저는 속성에 기본적인 논문 정보를 끌어왔고요, 이후에 제목, 학회, DOI링크를 한 번 더 표시해 주었습니다.

abstract 내용도 바로 확인할 수 있도록 배치해 주었어요.

다음은 우리가 열심히 하이라이트하고 comment단 내용들을 불러와야겠죠?

저는 항상 하이라이트한 문장 + 내 comment 순으로 오도록 배치했어요.

comment가 없다면 문장만 등장합니다.

그리고 제가 언급했던 5가지 내용들을 스스로 정리할 공간이 필요해서 마지막엔 5개 콜아웃을 배치했어요.

그래서 제 템플릿을 Zotero와 함께 사용하면

Zotero만 사용해서 정독 + 필요한 부분 메모
Obsidian으로 불러와서 중요내용 확인
나만의 내용 정리

까지 진행할 수 있답니다!

저의 템플릿은 아래 첨부파일을 확인해주세요!

Zotero Template.md

0.00MB

이 템플릿은 제가 논문을 읽는 방식에 맞추어 제가 만들어낸 저의 창작물입니다.

2차가공을 하셔서 개인적으로 사용하시는 건 괜찮지만, 상업적인 사용은 금하며, 공유할 때는 꼭 출처를 밝혀주시면 감사하겠습니다 :)

저는 https://github.com/community-archive/obsidian-zotero-integration/blob/main/docs/README.md 를 참고해서 템플릿을 만들었어요.

완전히 다른 형식의 템플릿을 제작하시고 싶다면 위 링크를 클릭하셔서 zotero integration 플러그인 개발문서를 참조하시면 좋을 것 같습니다!

그럼 위 템플릿을 적용해서 Zotero에 있는 내용을 Obsidian으로 불러오는 방법을 설명드리겠습니다.

우선 cmd + z로 명렁어 선택을 실행시켜요. (맥북기준)

불러오고자 하는 논문을 선택합니다. (여러 개를 동시에 선택할 수도 있어요.)

체크 표시를 눌러주면 짠! 우리가 지정한 폴더에 잘 불러와진 것을 확인할 수 있어요!

오늘 제 포스팅이 논문을 읽고 내용을 정리하는 데 많은 도움이 되었으면 좋겠습니다!!

랩실 주말 출근하고

야밤에 쓰는 포스팅이라

정신이 혼미하네요...

이전 포스팅이 궁금하시다면,,,

https://easy1nhard2.tistory.com/35

영국 방문연구원의 Zotero로 논문 읽는 방법!

easy1nhard2.tistory.com

다들 보람찬 연구생활 하시길...

영국 방문연구원의 Zotero로 논문 읽는 방법!

orieasy1 — Fri, 7 Aug 2026 03:13:05 +0900

️ 공학계열 논문 읽는법, Zotero 사용법

안녕하세요..?

오랜만입니다.... 껄껄

저는 25년도 중반까지, 그리고 특히 24년에 개발자가 되겠다는 꿈을 안고,,

최대한 부지런히 tech blog를 썼던 사람입니다...

그 시절에 썼던 글들을 아직도 봐주시더라고요,,,

(감사합니다)

하지만 3학년이 너무 힘들었고... (시간적인 여유도 없을 뿐더러)

대학원에 진학하겠다는 결심을 하고 나서 보니 사실 개발 관련해 할 얘기가.. 많이 없기도 했습니다.

꾸준히 개발(학교 팀플, 실험 시스템 제작)등을 하긴 했지만, 개발 관련 공부를 한 것도 아니고, 바이브 코딩을 하기도 했기때문에 특별히 적을 내용이 없다는 생각이 들기도 하더라고요,,,

그래서 중간중간 개발 얘기도 있겠지만 논문 리뷰에 초점을 맞춰서 이 블로그를 운영해 볼까 합니다.

+ 노션, 옵시디언과 같은 생산성 어플리케이션 이야기도 함께요

그래서 오늘의 주제는 "논문 읽는 법"

(두둥)

논문도 읽어 버릇해야 한다고 이제야 조금씩 어떻게 읽어야 하는 건지 감이 오는 것 같습니다.

처음 논물을 읽게 되면 사실 방법을 모르는 것도 모르는 거지만, 보통 본인의 관심사라서 보는게 아니라 교수님, 선배님께서 던져주시는 주제, 논문을 많이 읽어서 더 혼란스러울 수 있다고 생각합니다.

무엇보다 논문을 읽을 때 중요한 건 '내가 왜 이 논문을 읽는지', '이 논문에서 무엇을 얻어갈 것인지'를 계속 생각하면서 읽는 태도입니다.

목적이 분명할수록 기억에 오래 남고 여러 관점에서 논문을 읽으면서 내 것을 만들어 갈 수 있기 때문입니다.

남들의 추천으로 읽게 된 논문이라도 해당 논문에서 내가 어떤 걸 얻어갈지에 대해 고민하면 좋겠습니다.

저는 컴퓨터공학 논문 특히 HCI, Human-Computer Interaction 분야의 논문을 많이 찾아봅니다.

그래서 지금 말씀드리는 방법론도 공학계열 논문 중심 내용임을 감안하고 읽어주시면 좋을 것 같습니다.

저는 예를 들어 실험방법론과 실험시스템 설계에 대해 고민이 될 때 논문을 특히 많이 찾아보는것 같은데요, 사실 그러면 다른 파트보다 해당 내용이 나오는 파트를 먼저, 중심적으로 읽어보는 것 같습니다.

(Abstract을 읽고 바로 Methodology 파트로 넘어감)

그러면 다시 처음으로 돌아가서

1. 읽을 논문을 어떻게 선정하나요?

첫번째, Google Scholar

보통 구글 Scholar에서 검색을 많이 합니다.

https://scholar.google.com/

Google 학술 검색

거인의 어깨에 올라서서 더 넓은 세상을 바라보라 - 아이작 뉴턴 죄송합니다. 자바스크립트를 사용하도록 설정하지 않으면 일부 기능이 작동하지 않을 수 있습니다. 최적의 상태로 사용하려면

scholar.google.com

Google Scholar에서 검색을 할 땐 키워드 검색이 중요한데, 저는 주로 키워드 선정에서는 AI의 도움을 받습니다.

예를 들어서 "~주제에 대해 공부를 하고 싶어. Google Scholar에 검색할 키워드 좀 정리해줘." 혹은 "~ 가 고민이어서 논문을 좀 찾아보려고 해. Google Scholar에 검색할 키워드 좀 정리해줘." 식으로 LLM(지피티, 제미나이, 클로드 등등)에 요청을 하고 나온 키워드로 검색을 돌려보는 편입니다.

(키워드를 꽤 괜찮게 뽑아줍니다.)

그리고 선정하실 때 해당 학회, 컨퍼런스, 저널이 믿을 만한지, 해당 저자의 논문 활동이 최근까지 활발한지를 주로 체크해 보는 것 같습니다.

마음에 드는 연구자나 교수님이 나타나면 해당 저자나 저자가 속해 있는 팀의 논문을 발행 연도나 주제별로 읽어 보기도 합니다.

두번째, Reference 논문 타고 타고 보기

그리고 꼬리에 꼬리를 무는 방법도 추천합니다.

하나의 논문을 읽어 내려가면서 reference로 사이트된 논문을 읽어 보는 겁니다.

예를 들어서 방법론이 궁금해서 해당 논문을 읽어 보고 있었다고 합시다.

저기 3.3 Tasks and Procedure 파트에 위치한 adapted from the study procedure [51] 보이시나요?

[]안에 위치한 번호의 논문의 방법론을 반영했다는 뜻인데요.

그리고 51번 레퍼런스 논문으로 이동해서 그 논문도 함께 읽어 보는 것입니다.

해당 방법은 처음 연구를 시작하는 분들, 그러니까 학부 연구생분들한테 특히 추천합니다.

Related Work 세션은 건너뛰어도 된다라는 말 종종 들어보셨을 꺼예요.

하지만 해당 분야를 처음 접하시는 분들 한테는 보물 같은 세션입니다. 누군가 관련 자료를 다 읽고 정리해두었다는 뜻이니까요.

Related Work 세션에 사이트된 reference 논문을 읽다보면 해당 분야의 고전 논문부터 중요한 개념을 공부할 수 있습니다.

세번째, 학회 공식 사이트 활용

관심 있는 분야의 학회 사이트를 사용하는 것도 방법입니다.

먼저 해당년도 conference 홈페이지에 들어가서 paper들을 확인하는 방법이 있습니다.

해당 학회 + 년도 + program을 치면 발표 순서별로? 날짜별로? 논문들을 확인할 수 있어요.

최근 컨퍼런스에서 발표된 논문들을 위주로 확인하고 공부하려할 때, 연구 트렌드를 보고 싶을 때 제가 많이 사용하는 방법입니다.

예를 들어 제가 올해 CHI conference에서 발표된 논문들을 보고 싶으면 CHI 2026 Programs 라고 구글에 검색해서 찾아봅니다.

학회 주최측의 digital library를 살펴보는 방법도 있습니다.

CHI는 ACM이 주최하고 ISMAR는 IEEE가 주최하는데요, 그려면 ACM Digital Library, IEEE Digital Library라고 구글에 검색해보는거죠.

이런식으로요.

해당 디지털 라이브러리에서 검색하면 해당 주최즉 저널, 컨퍼러스의 논문들만 볼 수 있습니다.

내가 특히 원하는 학회, 신뢰도 있는 컨퍼런스, 저널의 논문을 보고싶을 때 쓸수 있는 방법이죠.

2. 읽는 방법 + 논문 읽는 앱 추천

어떤걸 생각하면서, 어떤 순서로 읽어야 하나요?

개인적으로 논문을 읽을 때 생각해야하는 것, 논문을 읽은 뒤 얻어가야하는 것은 크게 5가지라고 생각합니다.

이 논문의 RQ와 Contribution
실험 설계 및 분석방법론
논문의 결과
논문의 한계
이 논문과 내 연구와의 관계성

Research Question과 Contribution, 당연히 이 논문이 어떤 문제를 해결하려 했고 어떤 기여를 했는지를 살펴봐야겠죠.

실험 설계 및 분석 방법론을 살펴보는 것도 중요합니다.

어떤 이유 때문에 이런 설계를 했고 여러 분석 방법 중에 해당 방법을 선택했는지를 알아야 추후 내 연구에서도 해당 사항을 반영할 수 있으니까요.

아마 Discussion 혹은 Future work 세션에 저자들이 생각하는 논문의 한계점을 명시해 두었을 겁니다.

그것과 더불어 내가 생각하는 해당 논문의 한계점, 그리고 의문이 드는 점도 함께 정리해 두었다가 해결하는 것도 좋을 것 같습니다.

마지막으로 해당 논문과 내 연구와의 관계성입니다.

해당 논문을 Base로 한다면 정말 꼼꼼히 읽어야 할 것이고 인용이나 방법론 착안을 위한 것이라면 해당 섹션을 자세히 읽는 것만으로도 충분할 겁니다.

저는 보통 abstract -> intro에서 RQ와 Contribution만 간단하게 체크 -> method -> result -> discussion & contribution 하는 편입니다.

방법론이 궁금해서 읽는다면 abstract만 읽고 해당 스터디의 method와 result만 읽고 넘어가기도 합니다.

그러나 정말 제 연구의 baseline이 되는 논문이라면 Related Work까지 모두 꼼꼼하게 읽는 편입니다.

하지만 Related Work는 보통 제일 마지막에 읽는 편이에요.

논문을 읽을 때 추천하는 어플리케이션: Zotero

바로 Zotero입니다.

정말 유명한 애플리케이션인데요, 많은 연구자분들께서 이미 사용하고 계시죠.

다운로드 링크 ⬇️

https://www.zotero.org/

Zotero | Your personal research assistant

www.zotero.org

제가 Zotero를 좋아하는 이유는 프로젝트별로 논문을 구분해서 저장할 수 있고, 하이라이트와 Comment 기능 때문입니다.

논문을 읽으면서 중요하다고 생각하는 부분에 하이라이트를 치고 코멘트를 바로바로 달 수 있어요.

Zotero 사용 예시

사실 많은 분들이 논문을 읽는데 LLM을 많이 사용하고 계실꺼예요.

저도 그렇고요.

LLM이 요약정리, 번역 모두 잘해주긴하지만 사용을 하면 할수록 지날수록 영어문장을 해석하는 방향성이나 구조를 파악하는 능력이 떨어지는 것 같다는 느낌이 들더라고요.

그래서 지금은 문장별로 번역을 시킨 다음에 Zotero를 사용해서 문장 구조를 확인해가면 필요하거나 중요한 내용은 메모를 하는 방식으로 사용하고 있답니다.

이렇게 하니까 논문을 읽는 힘이 생기는 것 같더라고요.

LLM 의존도 비교적 줄고요.

Zotero는 Chorme 확장 프로그램과 함께 동작해요.

확장프로그램을 사용해서 논문 웹사이트에서 바로바로 자기가 원하는 Zotero 폴더로 논문을 저장할 수 있죠.

바로 이렇게요

⬇️

그래서 프로젝트끼리 논문을 관리할 수 있고, 나중에 논문 작성 시 Reference로 사이트할 논문을 찾기도 비교적 수월하답니다!

그리고 Zotmoov를 사용하실 때 Zotmoov라는 플러그인을 함께 사용하시는 걸 추천들려요!!

크롬 확장 프로그램으로 논문들을 저장할 때 원래 여러 경로에 마구잡이로 저장되거든요.

Zotmoov를 사용하시면 지정한 폴더로 저장할 수 있어요.

Zotmoov 설치링크⬇️

https://github.com/wileyyugioh/zotmoov

GitHub - wileyyugioh/zotmoov: Zotero plugin to automatically move attachments and link them

Zotero plugin to automatically move attachments and link them - wileyyugioh/zotmoov

github.com

설정하는 방법도 간단해요!

위 링크로 들어가신 뒤, 아래 사진의 Download the latest release here을 클릭해서 들어가주세요!

그럼 아래 화면이 나타나는데요, xpi 확장자의 파일을 다운받아주세요!

그다음 Zotero > Tools > Plugins에 들어가신 뒤, Install Plugins Form File을 클릭해주세요.

그런 다음 다운받은 xpi 확장자 플러그인 파일을 클릭하시면 아래 처럼 설치된 걸 보실 수 있습니다!

그런 다음 해당 창을 닫고 Settings 창에 들어가시면 어디 디렉토리 밑으로 논문 파일들을 저장할지 설정하실 수 있어요.

해당 플러그인을 사용하기 전에 이미 저장해둔 논문이 있으시다면

논문 목록에서 우클릭 > ZotMoov: Move Selected to Directory를 사용해서 이동시킬 수 있습니다!!

여기까지가 기본적인 논문읽는 방법과 Zotero 사용법이었어요!

그렇다면 저 코멘트들 한 번에 가독성 좋게 볼 수 있는 방법이 없을까.. 라는 생각이 드실텐데요,

Obsidian을 사용하면 완전 편리하게! 해당 내용을 Obisidian 노트로 가져올 수 있답니다!

해당 내용과 관련된 방법론과 템플릿은 다음 포스팅에서 공유해드릴테니 확인해주세요!!

이상 오늘 포스팅 내용을 마무리 하겠습니다.

기록과 정리에 미친 저의 obsidian, 노션 활용법 포스팅을 앞으로도 꾸준히 들고 올테니 확인해주시면 감사하겠습니다 :)

[LangChain] 7. 텍스트 분할 (Text Splitter)

orieasy1 — Sun, 4 Jan 2026 20:40:17 +0900

01. 문서 분할이란?

문서분할(Text Spliter)

RAG의 2단계로, 로드된 문서를 LLM이 처리하기 좋은 작은 조각(청크) 으로 나누는 과정
크고 복잡한 문서를 LLM 이 받아들일 수 있는 효율적인 작은 규모의 조각으로 나누는 작업
시스템이 정보를 보다 잘 활용할 수 있도록

목적: 나중에 사용자가 입력한 질문에 대하여 보다 효율적인 정보만 압축/선별하여 가져오기 위함

분할의 필요성

핀포인트 정보 검색(정확성):
문서를 세분화함으로써 질문(Query) 에 연관성이 있는 정보만 가져오는데 도움이 됨.
각각의 단위는 특정 주제나 내용에 초점을 맞추므로, 관련성이 높은 정보를 제공함.
리소스 최적화(효율성):
전체 문서를 LLM 으로 입력하게 되면 비용이 많이 발생할 뿐더러, 효율적인 답변을 많은 정보속에 발췌하여 답변하지 못하게 됨. 때로는 이러한 문제가 할루시네이션으로 이어지게 됨 → 답변에 필요한 정보만 발췌

문서 분할 과정

문서 구조 파악: PDF 파일, 웹 페이지, 전자 책 등 다양한 형식의 문서에서 구조를 파악 (문서의 헤더, 푸터, 페이지 번호, 섹션 제목 등을 식별하는 과정을 포함)
단위 선정: 문서를 어떤 단위로 나눌지 결정 (ex. 페이지별, 섹션별, 또는 문단별일 수 있으며, 문서의 내용과 목적에 따라 다름)
단위 크기 선정(chunk size): 문서를 몇 개의 토큰 단위로 나눌 것인지를 정함.
청크 오버랩(chunk overlap): 분할된 끝 부분에서 맥락이 이어질 수 있도록 일부를 겹쳐서(overlap) 분할하는 것이 일반적

02. CharacterTextSplitter

기본적으로 "\n\n" 을 기준으로 문자 단위로 텍스트를 분할

텍스트 분할 방식: 단일 문자 기준
청크 크기 측정 방식: 문자 수 기준

파일 로딩

# data/appendix-keywords.txt 파일을 열어서 f라는 파일 객체를 생성합니다.
with open("./data/appendix-keywords.txt") as f:
    file = f.read()  # 파일의 내용을 읽어서 file 변수에 저장합니다.

CharacterTextSplitter 설정

from langchain_text_splitters import CharacterTextSplitter

text_splitter = CharacterTextSplitter(
    # 텍스트를 분할할 때 사용할 구분자를 지정
    # separator=" ",
    # 분할된 텍스트 청크의 최대 크기를 지정
    chunk_size=250,
    # 분할된 텍스트 청크 간의 중복되는 문자 수를 지정
    chunk_overlap=50,
    # 텍스트의 길이를 계산하는 함수를 지정
    length_function=len,
    # 구분자가 정규식인지 여부를 지정
    is_separator_regex=False,
)

매개변수	설정값	의미
separator	기본값 \n\n	문단 단위 분할
chunk_size	250	청크 최대 문자 수
chunk_overlap	50	인접 청크 간 중복 문자 수
length_function	len	길이 계산 기준 = 문자 수
is_separator_regex	False	separator를 일반 문자열로 처리

문서 분할

text_splitter를 사용하여 file 텍스트를 문서 단위로 분할

texts = text_splitter.create_documents([file])
print(texts[0])  # 분할된 문서 중 첫 번째 문서를 출력합니다.

출력:

메타데이터 포함 분할

metadatas = [
    {"document": 1},
    {"document": 2},
]  # 문서에 대한 메타데이터 리스트를 정의합니다.
documents = text_splitter.create_documents(
    [
        file,
        file,
    ],  # 분할할 텍스트 데이터를 리스트로 전달합니다.
    metadatas=metadatas,  # 각 문서에 해당하는 메타데이터를 전달합니다.
)
print(documents[0])  # 분할된 문서 중 첫 번째 문서를 출력합니다.

출력:

순수 문자열 분할

# text_splitter를 사용하여 file 텍스트를 분할하고, 분할된 텍스트의 첫 번째 요소를 반환
text_splitter.split_text(file)[0]

출력:

03. 재귀적 문자 텍스트 분할 (RecursiveCharacterTextSplitter)

RecursiveCharacterTextSplitter는 일반적인 텍스트 문서에 가장 권장되는 분할 방식
이 분할기는 여러 개의 문자 구분자 목록을 순차적으로 적용하여, 청크가 충분히 작아질 때까지 재귀적으로 텍스트를 분할

단순히 하나의 기준으로 자르는 것이 아니라, 의미 단위를 최대한 유지하면서 점진적으로 잘게 나누는 것이 핵심.

텍스트가 분할되는 방식: 문자 목록(["\n\n", "\n", " ", ""]) 에 의해 분할됩니다.
청크 크기가 측정되는 방식: 문자 수에 의해 측정됩니

기본 동작 원리

기본 문자 목록: ["\n\n", "\n", " ", ""]
분할 시도 순서
1. 단락 (\n\n)
2. 문장 (\n)
3. 단어 ( )
4. 문자 ("", 최후 수단)

먼저 큰 의미 단위를 유지하려 시도하고 청크 크기를 초과할 경우 더 작은 단위로 재귀적으로 분할

파일 로딩

# data/appendix-keywords.txt 파일을 열어서 f라는 파일 객체를 생성합니다.
with open("./data/appendix-keywords.txt") as f:
    file = f.read()  # 파일의 내용을 읽어서 file 변수에 저장합니다.

RecursiveCahrarcterTextSplitter 설정

from langchain_text_splitters import RecursiveCharacterTextSplitter

text_splitter = RecursiveCharacterTextSplitter(
    # 분할된 텍스트 청크의 최대 크기를 지정
    chunk_size=250,
    # 분할된 텍스트 청크 간의 중복되는 문자 수를 지정
    chunk_overlap=50,
    # 텍스트의 길이를 계산하는 함수를 지정
    length_function=len,
    # 구분자가 정규식인지 여부를 지정
    is_separator_regex=False,
)

매개변수	설정값	의미
separators	기본값 ["\n\n", "\n", " ", ""]	재귀적 분할 기준 문자
chunk_size	250	청크 최대 문자 수
chunk_overlap	50	인접 청크 간 중복 문자 수
length_function	len	길이 계산 기준 = 문자 수
is_separator_regex	False	구분자를 일반 문자열로 처리

문서 분할 (Document 객체 반환)

RecursiveCharacterTextSplitter를 사용하여 file 텍스트를 문서(Document) 단위로 분할

분할된 문서는 texts 리스트에 저장됨

texts = text_splitter.create_documents([file])

print(texts[0])  # 첫 번째 문서 출력
print("===" * 20)
print(texts[1])  # 두 번째 문서 출력

출력:

순수 문자열 분할

# 텍스트를 분할하고 분할된 텍스트의 처음 2개 요소를 반환
text_splitter.split_text(file)[:2]

출력:

04. 토큰 텍스트 분할(TokenTextSplitter)

대부분의 언어 모델(LLM)은 입력 가능한 토큰 수에 제한이 있음.
따라서 문서를 분할할 때 문자 수가 아니라 토큰 수 기준으로 관리해야 하는 경우가 많음.

TokenTextSplitter는 텍스트를 토큰 개수를 기준으로 청크(chunk)로 분할하는 데 사용되는 분할기

문자 수 기준 분할은 실제 토큰 수를 초과할 위험 존재
토큰 기준 분할은:
- 모델 입력 제한을 안전하게 만족
- 특히 embedding, generation 단계에서 필수

CharacterTextSplitter	문자	문자 수	가장 단순
RecursiveCharacterTextSplitter	문자(재귀)	문자 수	의미 보존 ⭕
TokenTextSplitter	토큰	토큰 수	LLM 안전 ⭕
tiktoken + Recursive	재귀 + 토큰	토큰 수	실무 최적
spaCy / NLTK	문장	문자 수	NLP 전통 방식
KoNLPy	형태소	문장	한국어 특화

tiktoken

tiktoken이란?

OpenAI에서 만든 빠른 BPE(Byte Pair Encoding) 토크나이저
GPT 계열 모델과 동일한 토큰 계산 방식 사용

%pip install --upgrade --quiet langchain-text-splitters tiktoken

파일 로딩

withopen("./data/appendix-keywords.txt")as f:
    file = f.read()

tiktoken 기반 분할 (CharacterTextSplitter 활용)

from langchain_text_splittersimport CharacterTextSplitter

text_splitter = CharacterTextSplitter.from_tiktoken_encoder(
    chunk_size=300,
    chunk_overlap=0,
)

texts = text_splitter.split_text(file)

분할 자체는 CharacterTextSplitter 방식
청크 크기 계산에만 tiktoken 사용

⚠️ 주의

분할된 텍스트가 실제 모델 토큰 제한을 초과할 수도 있음

권장 대안

RecursiveCharacterTextSplitter.from_tiktoken_encoder

토큰 기준 크기를 초과하면 재귀적으로 재분할
실제 LLM 입력 제한을 넘지 않도록 보장

TokenTextSplitter

TokenTextSplitter는 처음부터 토큰 단위로 텍스트를 분할

from langchain_text_splittersimport TokenTextSplitter

text_splitter = TokenTextSplitter(
    chunk_size=200,
    chunk_overlap=0,
)

texts = text_splitter.split_text(file)

분할 기준: 토큰
청크 크기: 토큰 수 기준
LLM 입력 안정성 ⭕
의미 단위 유지 ❌ (문단/문장 고려 없음)

기타 토크나이저 기반 분할기

spaCy 기반 분할

spaCy tokenizer 사용
문장 단위 분할에 강점
chunk size 측정은 문자 수 기준

import warnings
from langchain_text_splitters import SpacyTextSplitter

# 경고 메시지를 무시합니다.
warnings.filterwarnings("ignore")

# SpacyTextSplitter를 생성합니다.
text_splitter = SpacyTextSplitter(
    chunk_size=200,  # 청크 크기를 200으로 설정합니다.
    chunk_overlap=50,  # 청크 간 중복을 50으로 설정합니다.
)

NLTK 기반 분할

Natural Language Toolkit (NLTK)은 Python 프로그래밍 언어로 작성된 영어 자연어 처리(NLP)를 위한 라이브러리와 프로그램 모음

NLTK tokenizer 기반
비교적 단순한 문장 분할

from langchain_text_splitters import NLTKTextSplitter

text_splitter = NLTKTextSplitter(
    chunk_size=200,  # 청크 크기를 200으로 설정합니다.
    chunk_overlap=0,  # 청크 간 중복을 0으로 설정합니다.
)

SentenceTransformersTokenTextSplitter

sentence-transformer 모델 전용
모델의 토큰 윈도우 크기에 맞게 분할

from langchain_text_splitters import SentenceTransformersTokenTextSplitter

# 문장 분할기를 생성하고 청크 간 중복을 0으로 설정합니다.
splitter = SentenceTransformersTokenTextSplitter(chunk_size=200, chunk_overlap=0)

embedding 모델 최적화

KoNLPy (한국어)

한국어는 영어와 구조가 다르므로 전용 토크나이저 필요
KoNLPy의 Kkma 형태소 분석기 사용 가능

from langchain_text_splitters import KonlpyTextSplitter

# KonlpyTextSplitter를 사용하여 텍스트 분할기 객체를 생성합니다.
text_splitter = KonlpyTextSplitter()

texts = text_splitter.split_text(file)  # 한국어 문서를 문장 단위로 분할합니다.
print(texts[0])  # 분할된 문장 중 첫 번째 문장을 출력합니다.

Hugging Face Tokenizer

GPT2TokenizerFast 등 사용 가능
Hugging Face 토크나이저 기준으로 토큰 길이 계산

text_splitter = CharacterTextSplitter.from_huggingface_tokenizer(
    # 허깅페이스 토크나이저를 사용하여 CharacterTextSplitter 객체를 생성합니다.
    hf_tokenizer,
    chunk_size=300,
    chunk_overlap=50,
)
# state_of_the_union 텍스트를 분할하여 texts 변수에 저장합니다.
texts = text_splitter.split_text(file)

05. 시멘틱 청커 (SemanticChunker)

SemanticChunker란?

SemanticChunker는 텍스트를 의미론적 유사성(semantic similarity) 에 기반하여 분할하는 텍스트 분할기

기존의 문자/토큰 기준 분할과 달리, 문장의 의미 변화 지점을 기준으로 청크를 나눔

LangChain의 실험적(experimental) 기능이며, Greg Kamradt의 아이디어와 노트북을 기반으로 구현되었습니다.

핵심 아이디어

“의미가 크게 바뀌는 지점에서 문서를 나눈다”

텍스트를 문장 단위로 분리
인접 문장 간 임베딩 거리(차이) 계산
의미 차이가 충분히 크면 → 분할 (breakpoint)

동작 방식 개요

텍스트를 문장 단위로 분할
문장 임베딩 생성 (OpenAI Embeddings 등)
인접 문장 간 임베딩 거리 계산
임계값(threshold)을 초과하는 지점에서 분할
의미적으로 유사한 문장들은 하나의 청크로 병합

파일 로딩

with open("./data/appendix-keywords.txt") as f:
    file = f.read()

SemanticChunker 생성

from langchain_experimental.text_splitter import SemanticChunker
from langchain_openai.embeddings import OpenAIEmbeddings

text_splitter = SemanticChunker(OpenAIEmbeddings())

임베딩 모델 필수
OpenAI Embeddings 외에도 다른 임베딩 모델 사용 가능
텍스트 분할

chunks = text_splitter.split_text(file)
print(chunks[0])

반환 타입: List[str]
문단/문자 기준이 아닌 의미 단위 기준 분할

Document 객체로 변환

docs = text_splitter.create_documents([file])
print(docs[0].page_content)

반환 타입: LangChain Document
RAG 파이프라인에 바로 사용 가능

Breakpoint (분리 기준점)

SemanticChunker는 문장을 “어디서 나눌지” 결정하는 방식이 핵심

이는 문장 간 임베딩 차이를 기준으로 판단

분할 기준점 방식 (Threshold Types)

Percentile (백분위수, 기본값)

text_splitter = SemanticChunker(
    OpenAIEmbeddings(),
    breakpoint_threshold_type="percentile",
    breakpoint_threshold_amount=70,
)

문장 간 거리 분포 계산
상위 N% 이상 차이가 나는 지점에서 분할
상대적으로 안정적이고 일반적인 설정

Standard Deviation (표준편차)

text_splitter = SemanticChunker(
    OpenAIEmbeddings(),
    breakpoint_threshold_type="standard_deviation",
    breakpoint_threshold_amount=1.25,
)

평균 대비 표준편차 이상 차이가 날 경우 분할
강한 의미 변화만 분할

Interquartile Range (사분위수 범위)

text_splitter = SemanticChunker(
    OpenAIEmbeddings(),
    breakpoint_threshold_type="interquartile",
    breakpoint_threshold_amount=0.5,
)

IQR 기반으로 이상치 수준의 의미 변화 감지
percentile과 standard deviation의 중간 성격

06. 마크다운 헤더 텍스트 분할 (MarkdownHeaderTextSplitter

마크다운 문서의 헤더(#, ##, ### …) 구조를 읽어서헤더 단위(섹션 단위) 로 텍스트를 청크로 분할하는 splitter.

문서의 구조/맥락을 유지한 채 임베딩·검색(RAG)에 유리한 청크를 만들 때 유용.

분할 기준 설정: headers_to_split_on

headers_to_split_on = [
  ("#","Header 1"),
  ("##","Header 2"),
  ("###","Header 3"),
]

어떤 레벨의 헤더를 “경계”로 볼지 지정.
두 번째 값("Header 1" 등)은 결과 메타데이터 키로 사용됨.

결과 형태: split_text() → Document 리스트

# 마크다운 헤더를 기준으로 텍스트를 분할하는 MarkdownHeaderTextSplitter 객체를 생성
markdown_splitter = MarkdownHeaderTextSplitter(headers_to_split_on=headers_to_split_on)
# markdown_document를 헤더를 기준으로 분할하여 md_header_splits에 저장
md_header_splits = markdown_splitter.split_text(markdown_document)

반환: List[Document]
각 Document는
- page_content: 해당 헤더 아래 내용
- metadata: 상위 헤더 정보가 누적되어 들어감
- 예) {'Header 1': 'Title', 'Header 2': '1. SubTitle', 'Header 3': ...}

섹션 맥락이 메타데이터로 유지된다는 것이 제일 큰 장점

헤더를 본문에서 제거/유지 옵션: strip_headers

기본값: strip_headers=True → 헤더 문자열은 page_content에서 제거

설정:

markdown_splitter = MarkdownHeaderTextSplitter(
    # 분할할 헤더를 지정합니다.
    headers_to_split_on=headers_to_split_on,
    # 헤더를 제거하지 않도록 설정합니다.
    strip_headers=False,
)

→ 헤더도 함께 포함해서 저장 가능 (“청크만 봐도 제목이 보이게” 하고 싶을 때 유용)

“헤더로 1차 분할 → 다른 splitter로 2차 분할” 가능

헤더 단위로 먼저 의미 있는 큰 덩어리를 만든 뒤, 그 안에서 토큰/문자 기준으로 더 잘게 나눌 수 있음.

chunk_size = 200  # 분할된 청크의 크기를 지정
chunk_overlap = 20  # 분할된 청크 간의 중복되는 문자 수를 지정

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=chunk_size, chunk_overlap=chunk_overlap
)

장점: 구조 기반(헤더) 맥락 유지 + 크기 제어(chunk_size)
결과:
- 작은 청크로 잘려도 metadata에 헤더 정보가 계속 남음
- RAG에서 “어느 섹션에서 나온 내용인지” 추적 쉬움

07. HTML 헤더 텍스트 분할 (HTMLHeaderTextSplitter)

HTMLHeaderTextSplitter는 HTML 문서의 구조(<h1>, <h2>, <h3> …) 를 인식하여 헤더 단위로 텍스트를 분할하고, 각 청크에 구조 기반 메타데이터를 부여하는 구조 인식(structure-aware) 텍스트 분할기

개념적으로는 MarkdownHeaderTextSplitter의 HTML 버전이라고 보면 됨

핵심 목적

HTML 문서의 계층 구조를 보존
각 텍스트 청크에 “어떤 헤더 아래에 속하는지”를 메타데이터로 유지
의미적으로 관련된 텍스트를 대략적으로 하나의 그룹으로 묶음

HTML 문자열을 직접 사용하는 경우

분할 기준 설정

from langchain_text_splitters import HTMLHeaderTextSplitter

headers_to_split_on = [
    ("h1", "Header 1"),  # 분할할 헤더 태그와 해당 헤더의 이름을 지정합니다.
    ("h2", "Header 2"),
    ("h3", "Header 3"),
]

어떤 HTML 헤더 태그를 기준으로 분할할지 지정
"Header 1", "Header 2" 등은 metadata key로 사용됨

HTML 문자열 분할

# 지정된 헤더를 기준으로 HTML 텍스트를 분할하는 HTMLHeaderTextSplitter 객체를 생성
html_splitter = HTMLHeaderTextSplitter(headers_to_split_on=headers_to_split_on)

# HTML 문자열을 분할하여 결과를 html_header_splits 변수에 저장
html_header_splits = html_splitter.split_text(html_string)

예: Some text about the first subtopic of Bar. {'Header 1': 'Foo', 'Header 2': 'Bar main section', 'Header 3': 'Bar subsection 1'}

→ HTML 계층 구조가 그대로 메타데이터에 반영됨

한계 (중요)

HTMLHeaderTextSplitter는 다음 가정을 기반으로 동작: 헤더는 항상 관련 텍스트보다 위(부모·형제 노드)에 있다

하지만 실제 웹 페이지에서는 이 가정이 깨지는 경우가 많음.

08. 재귀적 JSON 분할 (RecursiveJsonSplitter)

RecursiveJsonSplitter는 JSON 데이터를 구조를 유지한 채 재귀적으로 분할하는 텍스트 분할기입니다.

JSON 객체를 깊이 우선 탐색(DFS) 하면서, 가능한 한 중첩 구조를 보존한 상태로 작은 JSON 청크(chunk)를 생성합니다.

핵심 목적

API 스펙(OpenAPI), 설정 파일, 로그 등 구조화된 JSON 문서를
RAG / 임베딩에 사용할 수 있도록 의미 단위(JSON 객체 단위) 로 분할

분할 기준 및 특성

텍스트 분할 기준: JSON 값(value) 단위
청크 크기 기준: 문자 수
중첩 객체: 가능한 한 유지
매우 긴 문자열 값: 분할하지 않음
리스트(list): 기본적으로 분할하지 않음

청크 크기를 엄격히 제어해야 한다면 RecursiveJsonSplitter → RecursiveCharacterTextSplitter 같은 후처리 파이프라인을 고려하는 것이 권장됨

RecursiveJsonSplitter 기본 사용

from langchain_text_splittersimport RecursiveJsonSplitter

splitter = RecursiveJsonSplitter(max_chunk_size=300)

# JSON을 재귀적으로 분할
json_chunks = splitter.split_json(json_data=json_data)

반환: JSON 형태의 작은 딕셔너리 조각들
구조가 깨지지 않음

Document / Text 형태로 변환

# JSON 데이터를 기반으로 문서를 생성합니다.
docs = splitter.create_documents(texts=[json_data])

# JSON 데이터를 기반으로 문자열 청크를 생성합니다.
texts = splitter.split_text(json_data=json_data)

# 첫 번째 문자열을 출력합니다.
print(docs[0].page_content)

print("===" * 20)
# 분할된 문자열 청크를 출력합니다.
print(texts[0])

주의사항
RecursiveJsonSplitter는 JSON 내 리스트(list)를 기본적으로 분할하지 않는다.
이 때문에 리스트가 포함된 객체는 max_chunk_size를 초과하는 청크가 생성될 수 있다.

필요한 경우 convert_lists=True 옵션을 사용하면, 리스트를 index:item 형태의 key-value 구조로 변환하여 더 잘게 분할할 수 있다.

[HCI] Survey 설문조사에 대하여

orieasy1 — Sun, 9 Nov 2025 17:44:54 +0900

아래 글은 Research Methods in Human-Computer Interaction(2nd Edition)을 읽고 정리한 글입니다.

HCI(인간-컴퓨터 상호작용)에서는 설문조사(survey)를 많이 사용한다.

피실험자에게 해당 시스템을 어떻게 느끼는 지 등의 기본적인 자료를 수집하는데 있어서 가장 쉬운 방법 중 하나이기 때문이다.

오늘은 연구 방법론으로써의 설문 조사를 체계적으로 이해하고 설계하는 법에 대해 다뤄보려고 한다.

서론: 왜 설문조사는 여전히 중요한가?

설문조사(Survey)는 사회과학과 공학 전반에서 가장 널리 사용되는 연구 방법 중 하나이다.

우리가 어떤 집단의 의견, 태도, 인식, 행동 패턴을 이해하고자 할 때 가장 먼저 떠올리는 방법이기도 하다.
HCI(Human–Computer Interaction) 연구에서도 설문은 사용자 경험, 기술 수용성, 인식 변화 등을 폭넓게 탐색하기 위한 기본 도구로 사용된다.

Survey는 well-defined and well-written set of questions to which an individual is asked to answer로 정의할 수 있다.

설문조사는 인구를 설명하거나 행동을 해석하고, 아직 충분히 탐색되지 않은 영역을 조사하는 데 효과적이다.

그러나 동시에 가장 비판받는 방법론 중 하나이기도 하다. 그 이유는 “쉬워 보이지만, 잘못 설계되면 신뢰하기 어려운 데이터를 낳기 때문”이다.

잘 설계된 설문은 방대한 집단으로부터 통계적으로 의미 있는 데이터를 수집할 수 있는 강력한 도구지만, 형식적이거나 검증되지 않은 설문은 오히려 연구의 신뢰성을 해친다.
따라서 설문은 단순한 질문지(questionnaire)가 아니라, 명확한 연구 목적·표집 설계·응답자 기준·분석 계획이 통합된 하나의 과학적 접근으로 다뤄져야 한다.

그래서 무엇보다 설문조사를 "잘 설계하는 것"이 중요하다.

설문은 대부분 자기기입식(self-administered) 형태로 진행된다.

즉, 연구자의 개입 없이 응답자가 스스로 작성한다.

이런 특성 때문에 인터뷰나 참여관찰과 같은 질적 연구에 비해 데이터의 깊이는 얕지만, 대신 넓은 범위의 표본을 빠르게 확보할 수 있다.

요약하자면, 설문조사는 “가장 적합하기 때문이 아니라, 가장 쉽기 때문에 선택되는 경우가 많다.” 하지만 HCI 연구에서는 단순히 ‘쉬운 방법’이 아니라, 잘 통제되고 체계적으로 설계된 설문이 사용자 경험을 정량적으로 이해하는 데 매우 유용하다.

설문조사의 장점과 한계

설문조사의 큰 장점 중 하나는 비용 대비 효율이 높다는 것이다.

온라인 도구(SurveyMonkey, Google Forms, Qualtrics 등)를 활용하면 짧은 시간 안에 수백 명 이상으로부터 데이터를 수집할 수 있다.
또한 지리적으로 분산된 사용자들로부터 동시에 응답을 받을 수 있어, 광범위한 인구 집단의 스냅샷(snapshot) 을 빠르게 얻을 수 있다.

설문은 또한 IRB(인간대상연구윤리위원회) 승인 절차에서도 비교적 non-intrusive으로 간주되며, 개인 인터뷰보다 부담이 적다.
이러한 이유로, HCI 연구에서 사용자 인식·태도·의도·만족도·특성 비교를 다루는 경우 설문은 가장 적절한 방법 중 하나다.

하지만 설문에는 명확한 한계가 있다.

첫째, 응답자가 기억에 의존하는 문항(예: ‘지난주에 이 앱을 몇 번 사용했습니까?’)은 회상 오류(recall bias)가 발생할 수 있다.

둘째, 흥미로운 패턴이 나타나더라도 즉각적인 후속 질문(follow-up) 이 불가능하다.

셋째, 문항이 불명확하거나 편향되어 있다면, 응답자는 의도와 다르게 답할 수 있고 결과의 타당성이 급격히 떨어진다.

따라서 설문조사는 깊은 정성적 이해를 제공하지는 못하지만, 정확한 표집 설계와 문항 구성만으로도 전체 사용자 집단의 경향을 예측할 수 있는 도구가 된다.

HCI 연구에서는 종종 실험이나 인터뷰 등 다른 방법과 결합해 “보완적 수단” 으로 사용된다.

연구 대상과 설문 목표 설정

설문조사는 많은 사람들로부터 데이터를 수집할 수 있기 때문에, 연구자는 우선 “누구로부터 응답을 받을 것인가?”를 명확히 해야 한다.

이를 위해 대상 집단(Target Population), 대상 응답자(Targeted Respondents), 그리고 포함 기준(Inclusion Criteria) 이라는 세 가지 개념이 중요하다.

대상 집단: 연구자가 관심을 갖는 전체 인구.
예: “모바일 헬스 앱을 사용하는 20–40대 직장인”
대상 응답자: 실제로 설문을 받은 사람들.
포함 기준: 설문에 참여할 자격 조건.
예: “지난 한 달 내 앱 사용 경험이 있는 사람”

또한 설문을 배포할 때 필요한 모집단 프레임(population frame)—즉, 이메일 목록이나 사용자 데이터베이스—를 확보해야 한다.

HCI 연구에서는 이러한 명단이 불명확한 경우가 많기 때문에, 연구자는 종종 SNS, 커뮤니티, 혹은 컨퍼런스 네트워크 등을 활용한다.

만약 모집단이 명확히 정의되지 않았다면, 가능한 한 응답자 내 다양한 하위 집단(subgroup) 이 포함되도록 해야 한다.
예를 들어, “남녀, 연령대, 기술 숙련도”가 균형을 이루도록 표집을 설계하는 식이다..

확률 표집 Probabilistic Sampling

사회학에서 설문조사의 고전적인 목적은 전체 인구의 특성을 추정하는 것이다.
이를 가장 정확하게 달성하는 방법은 인구조사(census)이지만, 현실적으로는 불가능에 가깝다.

그래서 등장한 것이 확률 표집(probabilistic sampling) 이다.

확률 표집이란 모집단의 모든 구성원이 0보다 큰 확률로, 그리고 알려진 확률로 선택될 수 있는 표집 방식을 말한다.

즉, 각 참여자가 선택될 가능성이 명확히 정의되어 있고, 표본은 무작위로 선정된다.

예를 들어, 10,000명 중 500명을 무작위로 추출한다면, 이 500명은 전체 인구의 특성을 통계적으로 대변할 수 있다.

이 과정에서 포함 기준(inclusion criteria) 을 충족하고, 제외 기준(exclusion criteria) 을 위반하지 않아야 한다.

확률 표집은 “비용은 들지만, 일반화 가능성(generalizability)이 높은 방식”이다.
HCI 연구에서 IBM Beehive 연구(Chen et al., 2009)는 좋은 사례로, 전체 사용자 중 500명을 무작위로 선택해 230명의 유효 응답을 얻었다.

확률 표집은 또한 층화(Stratification) 기법을 사용해 대표성을 강화할 수 있다.

예를 들어, 미국 우체국의 주소 변경 데이터베이스에서 최근 이사한 6,000명을 표본으로 삼고, 이 중
1/3은 50마일 이내의 단거리 이사, 2/3은 장거리 이사로 나누는 식이다.
이는 장거리 이동이 중심 주제였기 때문에 특정 그룹의 비율을 조정한 것이다.

응답 규모(Response Size)는 신뢰수준(confidence level)과 허용 오차(margin of error)에 따라 달라진다.

Sue & Ritter(2007)에 따르면, 95% 신뢰 수준에서 ±5% 오차를 허용하려면 약 384명의 응답이 필요하다.

확률 표집의 주요 오류 유형

표집 오류(Sampling Error): 응답 수가 너무 적거나 표본이 충분히 대표하지 못할 때 발생한다.
예: 1만 명에게 발송했지만 100명만 응답.
포괄 오류(Coverage Error): 모집단의 일부가 조사 대상에서 제외될 때 발생.
예: 이메일 주소가 없는 사람은 조사 기회가 없음.
측정 오류(Measurement Error): 문항이 불명확하거나 편향된 경우.
비응답 오류(Nonresponse Error): 실제 응답자와 모집단의 통계적 구성이 다를 때.
예: 성별 비율이 모집단과 다름.

이러한 오류를 최소화하기 위해, 연구자는 표집 설계 단계에서부터 오차 요인을 예측하고 통제 전략을 마련해야 한다.

비확률 표집 Non-Probabilistic Sampling

앞서 다룬 확률 표집(probabilistic sampling) 은, 모집단의 모든 구성원이 동일하고 알려진 확률로 선택된다는 점에서 통계적으로 가장 이상적인 방식이다.

하지만 현실의 HCI 연구에서는 이런 이상적인 상황이 거의 없다.

예를 들어 “AI 어시스턴트를 사용하는 대학생”이나 “스마트워치를 쓰는 고령층” 같은 모집단은 명확하게 정의되어 있지도 않고, 중앙 데이터베이스나 공식 명단이 있는 것도 아니다.

이럴 때 연구자는 ‘무작위 추출(random)’이 불가능하다는 사실을 인정하고, 대신 실제 참여 가능한 사람들로부터 의미 있는 데이터를 수집하는 방향을 선택한다.
이게 바로 비확률 표집(non-probabilistic sampling) 이다.

왜 HCI에서는 비확률 표집이 흔한가?

HCI(Human–Computer Interaction) 연구의 목적은 단순히 모집단 전체의 평균을 추정하는 것이 아니라, ‘사람이 기술을 어떻게 경험하고 사용하는가’를 이해하는 것이다.

즉, “대표성(representativeness)”보다는 “맥락(context)”과 “경험의 다양성” 이 더 중요하다.

이 때문에 HCI 연구에서는 표본의 통계적 무작위성보다 현실적 접근성(accessibility) 을 우선시한다.

연구자는 실제로 시스템을 사용하는 사용자들을 중심으로 데이터를 수집하며, 이 과정에서 표집의 엄격한 통계적 기준보다는 연구의 목적에 부합하는 실질적 타당성을 추구한다.

비확률 표집의 주요 형태

HCI 설문 연구에서 자주 사용되는 대표적인 비확률 표집 방법은 다음 3가지이다.

1. 자발적 참여 패널 (Volunteer Panels)

연구 참여를 자발적으로 신청한 사람들을 모아두고, 필요할 때마다 연구에 참여시키는 방식이다.

예를 들어 한 대학의 UX 연구실이 “디지털 헬스 앱 사용자 패널”을 운영한다면, 이 패널을 활용해 다양한 실험이나 설문을 진행할 수 있다.

장점: 연구 주제에 관심이 많고 성실히 응답하는 참여자 확보 가능
단점: 기술 친숙도나 관심 수준이 일반 사용자보다 높아 편향이 생길 수 있음

즉, ‘품질은 높지만 일반화는 어렵다’는 특성이 있다.

2. 자기 선택 설문 (Self-Selected Surveys)

사용자가 스스로 참여를 선택하는 방식이다.

예를 들어 웹사이트에 “AI 챗봇 사용 경험 설문에 참여해 주세요”라는 배너를 띄우거나, SNS에 설문 링크를 공개하는 경우가 여기에 해당한다.

이 방식은 참여 장벽이 낮고 빠르게 데이터를 모을 수 있다는 장점이 있다.

하지만 반대로 주제에 강한 관심을 가진 사람들만 참여하기 때문에 편향(bias)이 생길 수 있다.
예를 들어 챗봇에 불만이 있는 사람만 설문에 참여한다면 결과가 부정적으로 쏠릴 수 있다.

그럼에도 불구하고, 아직 연구되지 않은 주제나 새로운 사용자 현상을 탐색할 때는 가장 자연스럽고 효과적인 시작점이 된다.
조지아 공대(Georgia Tech)의 HCI 연구팀도 이 방식을 활용해 초기 사용자 행동 패턴을 관찰하는 연구를 여러 차례 수행했다.

3. 눈덩이 표집 (Snowball Sampling)

이미 확보한 응답자가 다른 참여자를 소개하는 방식이다.
처음 확보한 응답자가 친구나 동료에게 설문을 공유하면서 ‘눈덩이처럼’ 표본이 커지는 구조다.

이 방식은 접근하기 어려운 집단을 연구할 때 특히 효과적이다.
예를 들어 시각장애인의 보조기기 사용 경험을 조사하려는 경우, 처음 몇 명의 참여자가 본인이 속한 커뮤니티에서 다른 사람을 연결해줄 수 있다.

장점: 신뢰 관계가 형성된 집단에서 빠르게 확산
단점: 사회적 네트워크가 유사한 사람들끼리 연결되므로 다양성이 부족할 수 있음

비확률 표집의 신뢰성 높이기

비확률 표집에서는 "통계적 일반화"보다는 데이터의 타당성(validity) 확보가 중요하다.

연구자는 다음과 같은 방법으로 신뢰성을 높일 수 있다.

인구통계학적 정보 수집(Demographic Data)
연령, 성별, 직업, 교육 수준 등 기본 정보를 통해 응답 집단의 다양성을 평가할 수 있다.
과표집(Oversampling)
모집단 규모를 정확히 모를 때는 가능한 한 많은 응답을 확보해야 한다.
응답 수가 많을수록 특정 집단이 완전히 배제될 가능성이 줄어들기 때문이다.
사용 행위 기반 표집(Random Sampling of Usage)
사용자 대신 ‘사용 행위’를 단위로 표집. 예: “웹페이지가 10번째 로드될 때마다 팝업 설문 표시”.
자기선택(Self-Selected) 설문
모든 방문자에게 설문 참여를 개방하는 방식. 예: 조지아 공대의 웹 설문(1994–1998)은 5,000명 이상의 응답을 확보했다.

설문 문항 개발

설문 문항 개발은 연구 설계 중 가장 섬세한 단계다.
응답자는 연구자의 도움 없이 스스로 설문을 읽고 작성해야 하므로, 모든 문항은 명확하고 중립적이며 이해하기 쉬워야 한다.

문항은 보통 세 가지 형식 중 하나로 구성된다.

개방형(Open-ended)
응답자가 자유롭게 의견을 기술.
→ 현상 이해에는 유용하지만, 분석이 어렵고 응답이 모호할 수 있다.
폐쇄형(Closed-ended)
- 순서형(Ordered): Likert 척도(1~5, 1~9 등)를 사용.
  예: “매우 만족 ~ 매우 불만족”
- 비순서형(Unordered): 논리적 순서가 없는 범주형 선택지.
  예: “성별”, “주 사용 디바이스”, “OS 종류”
복합형(Hybrid)
폐쇄형 문항 끝에 “기타(Other): _______”을 추가해 부분적 개방성을 부여.

피해야 할 문항 유형

이중질문(Double-barreled): “이 앱은 빠르고 유용했습니까?” → “빠르다고 느끼셨습니까?” / “유용했습니까?”로 분리해야 한다.
부정표현(Negative wording): “불편하지 않다고 생각하지 않습니까?”
편향된 단어(Biased wording): “전문가들이 추천한 앱을 사용했습니까?”
감정적 단어(Hot-button words): “불쾌한 경험이 있었나요?”보다는 “불편했던 점이 있었나요?”가 적절하다.

기존의 검증된 설문 도구 활용

HCI 분야에는 이미 수십 년간 사용되어 온 검증된 설문 도구들이 존재한다.

새로운 설문을 무조건 처음부터 제작할 필요는 없다.

오히려 기존 도구를 일부 수정하거나 부분적으로 사용하는 것이 더 타당할 수 있다.

대표적인 도구들은 다음과 같다.

CSUQ (Computer System Usability Questionnaire)
ICTQ (Interface Consistency Testing Questionnaire)
PUTQ (Perdue Usability Testing Questionnaire)
QUIS (Questionnaire for User Interaction Satisfaction)
SUMI (Software Usability Measurement Inventory)
WAMMI (Website Analysis and MeasureMent Inventory)

이 설문들은 이미 타당도와 신뢰도가 검증되어 있어, 사용성 평가나 인터페이스 만족도 측정에 활용하기 좋다.

종이 설문과 온라인 설문

오늘날 대부분의 설문은 온라인으로 진행된다.
웹 기반 설문은 개발이 빠르고 비용이 거의 들지 않으며, 데이터가 자동으로 저장되어 분석 속도도 빠르다.

그러나 모든 연구에 온라인 방식이 적합한 것은 아니다.
인터넷 접근이 어려운 집단(예: 노년층, 저소득층, 특정 장애 집단)은 배제될 위험이 있다.
따라서 연구자는 연구 목적과 대상의 접근성을 고려해 종이 설문, 이메일 설문, 웹 설문 중 가장 적절한 방식을 선택해야 한다.

실제로는 접근성(accessibility) 이 결정 요인이다.
정기적인 오프라인 모임을 통해 대상자를 직접 만날 수 있다면 종이 설문이 적합하고, 이메일 주소 목록이 있다면 메일 설문을, 온라인 커뮤니티 기반이라면 웹 설문이 효율적이다.

또한 두 방식을 병행하는 혼합형 설문(Mixed-mode survey) 도 가능하다.
이 경우 응답자의 선택권이 넓어지고 표본의 다양성이 커질 수 있다.

단, 서로 다른 포맷(예: 종이 vs 웹)은 시각적 구조 차이로 편향(bias)을 유발할 수 있으므로 주의해야 한다.

온라인 설문은 익명성이 보장될 때 민감한 주제에서 더 솔직한 응답을 유도한다는 연구 결과도 있다(Sussman & Sproull, 1999).
특히 웹 기반 자기기입식 설문은 면접 방식보다 응답자의 심리적 방어를 줄인다(Couper, 2005).

다만, IRB 기준상 온라인 참여 동의서(informed consent) 를 명시적으로 제시해야 한다.

설문 배포 이후의 절차

설문은 배포로 끝나지 않는다.
오히려 진짜 품질은 “배포 전후의 절차 관리”에서 결정된다.

설문 데이터의 신뢰성과 타당성은 파일럿 테스트(pilot test), 응답률 관리(response rate), 그리고 데이터 분석(data analysis) 단계에서 좌우된다.

Pilot Testing

파일럿 테스트는 설문 문항과 구조의 적합성을 검증하기 위한 예비 실험이다.

설문을 본격적으로 배포하기 전에, 소규모 집단을 대상으로 미리 테스트를 수행하여 문항의 명확성, 흐름, 기술적 오류를 점검한다.

가장 널리 사용되는 접근은 Dillman(2000)의 3단계 사전검증(pretesting) 과정이다.

전문가 검토(Expert Review)
연구 주제와 관련 있는 동료나 전문가에게 설문 초안을 검토받는다.
논리적 일관성, 문항의 의미 모호성, 편향적 표현 등을 점검한다.
사용자 피드백(User Feedback)
실제 응답자가 될 가능성이 있는 사람 2~3명을 대상으로 인터뷰를 진행한다.
설문을 작성하며 느낀 혼란, 흥미, 동기부여 수준 등을 탐색한다.
파일럿 조사(Pilot Study)
최종 후보 설문을 소규모 집단(대략 5~10명)에게 실제 배포한다.
수집된 응답을 바탕으로 응답 누락, 중복 선택, 기타 응답 비율 등을 확인하고 설문 도구를 수정한다.

이 단계에서 발견되는 오류는 대부분 단순하지만 치명적이다.
예를 들어 “응답자가 특정 문항을 건너뛰었거나, 한 문항에 두 개의 답을 한 경우”, 혹은 “너무 많은 사람들이 ‘기타(Other)’를 선택한 경우” 등이 있다.

이런 문제는 설문 배포 전에 반드시 제거되어야 하는 구조적 결함이다.

파일럿 규모는 전체 연구 크기에 따라 다르다.
작은 연구(200–300 응답 예상)는 5–10명의 파일럿으로 충분하지만, 대규모 연구(수만 명 대상)는 더 많은 파일럿 응답자가 필요하다.

단, 파일럿 참여자는 최종 분석에는 포함되지 않아야 한다.

Response Rate 관리

잘 설계된 설문이라도 응답률이 낮으면 데이터 품질이 급격히 떨어진다.
응답률은 단순히 숫자가 아니라, 표본의 대표성과 신뢰도를 보증하는 지표다.

응답률을 높이는 주요 전략은 다음과 같다.

사전 안내문(Pre-contact letter)
설문 발송 전에 “누가 연구를 수행하는지, 왜 중요한지, 얼마나 시간이 걸리는지”를 명확히 안내한다.
신뢰성과 투명성을 확보하는 단계이다.
응답 편의성 향상
종이 설문에는 **회신용 봉투(prepaid envelope)**를 동봉하고,
온라인 설문은 클릭 한 번으로 접근 가능한 짧은 URL과 모바일 친화형 화면을 제공한다.
리마인더(Reminder)
응답하지 않은 사람에게 1~2회 리마인더 메일을 보내는 것이 일반적이다.
Dillman의 5단계 연락 모델(5-step process) 은 응답률 향상에 특히 효과적이다.
- (1) 사전 안내문 발송
- (2) 설문 발송
- (3) 감사 및 리마인더 카드 발송
- (4) 2~4주 후 설문 재발송
- (5) 마지막으로 다른 채널(전화·이메일 등)로 접촉
인센티브 제공
설문 참여에 대한 보상은 소규모라도 효과적이다. 예: 추첨 쿠폰, 소정의 기념품, 연구 참여 증명서.

응답률이 20% 미만이라면, 표본 대표성에 심각한 문제가 있을 수 있다.
하지만 응답률이 40–60% 수준이면, 비확률 표본에서도 일정 수준의 타당성을 확보할 수 있다.

데이터 정제 및 분석

설문 데이터 분석은 크게 두 단계로 나뉜다.

정량 데이터 분석 (Quantitative Analysis)
- 기술통계(descriptive statistics): 빈도, 비율, 평균, 표준편차, 교차표(crosstabulation)
- 추론통계(inferential statistics): 상관관계, 회귀분석, 집단 간 차이검정 등
- 목적: 응답 패턴을 요약하고 가설을 통계적으로 검증한다.
정성 데이터 분석 (Qualitative Analysis)
- 개방형 문항(open-ended responses)은 코딩(coding) 작업을 거쳐 주제(theme)로 묶는다.
- 자연어 분석이나 키워드 빈도 분석을 통해 응답자 서술의 맥락을 이해한다.

이전에 수행해야 할 전처리 단계는 다음과 같다.

중복 응답 제거(duplicate filtering)
불완전 응답 제외(incomplete responses)
포함 기준(inclusion criteria) 미충족 응답자 제외
비정상 응답(패턴 반복, 극단치) 필터링

이 과정을 거쳐야만 통계적 신뢰성과 질적 타당성이 확보된다.

마무리 하며...

설문조사는 단순히 “많은 사람에게 물어보는 것”이 아니다.
HCI에서 설문은 사용자와 기술의 관계를 정량적으로 모델링하는 연구 방법이며, 잘 설계된 설문은 실험이나 로그 분석에서 포착하지 못하는 사람의 인식과 태도의 변화를 보여준다.

요약하자면, 설문은 다음과 같은 조건이 충족될 때 비로소 과학적 방법이 된다.

명확한 연구 목적과 변수 정의
– “무엇을 묻는가?”가 아니라 “왜 이걸 묻는가?”를 우선 정의한다.
표집의 정당성 확보
– 모집단이 명확하지 않더라도 포함 기준과 응답자 특성을 투명하게 명시한다.
문항의 타당성
– 이중질문, 부정문, 편향어, 감정어를 피한다.
파일럿 검증 및 응답률 관리
– 설문을 발송하기 전에 반드시 시험하고, 응답 유도 전략을 세운다.
적절한 분석 기법의 선택
– 단순한 빈도 분석을 넘어, 변수 간 관계를 추론하고 통찰을 도출한다.

HCI 연구자는 설문조사를 다른 연구 방법과 보완적(complementary) 으로 결합할 때 더 큰 효과를 얻을 수 있다.
예를 들어 로그 데이터나 사용자 실험 결과를 설문 응답과 결합하면, “행동(behavior)”과 “인식(perception)”의 간극을 분석할 수 있다.

결국 설문은 HCI 연구에서 사용자의 목소리를 데이터로 번역하는 첫 번째 도구다.
그리고 이 도구의 힘은, 얼마나 많은 응답을 모았는가가 아니라, 얼마나 정교하게 설계했는가에 달려 있다.

[Paper Review] AppAgent: Multimodal Agents as Smartphone Users

orieasy1 — Mon, 3 Nov 2025 01:16:05 +0900

오늘은 지난 1학기에 논문 세미나를 진행한 논문에 대한 리뷰를 작성해보고자 한다.

해당 논문에 대한 내용 전달보다는 해당 시스템을 직접 실행해보면서 느낀점을 위주로 작성해보고자하니 논문 내용이 궁금하다면 링크로 들어가 논문 내용을 읽어보길 바란다.

시간이 지날수록 LLM의 역할이 점점 더 다양해지고 있다.

LLM이 단순히 텍스트나 표, 이미지 등을 생성하는 도구를 넘어서 행동(Act)를 수행하는 에이전트로 진화하고 있다.

그중에서도 CHI 2025에 게재된 AppAgent: Multimodal Agents as Smartphone Users라는 논문이 이 흐름을 잘 보여주고 있지 않나라고 생각한다.

해당 논문에서는 기존 텍스트 기반 정보에만 의존했던 LLM Agent와 달리 이미지 처리 능력이 추가된 최신 LLM 모델을 바탕으로 사람의 행동을 모방하여 수행하는 LLM Agent를 개발하였다.

해당 논문 바로 가기

https://dl.acm.org/doi/full/10.1145/3706598.3713600

이 논문 LLM이 "사람처럼 스마트폰을 조작할 수 있을까?" 라는 질문에서 출발한다.

그래서 해당 시스템을 실행시켜보면 정말 사람처럼 수행한다고 느껴진다.

논문에서도 어떤 스마트폰 앱이든 조작할 수 있는 에이전트를 구축하는 것이 주요 도전 과제라고 설명하며 시스템 백엔드 접근과 함수 호출을 통해 동작하는 기존 에이전트와는 다르게 AppAgent의 경우, GUI에서 터치와 스와프 같은 저수준 작업을 사용하여 앱을 제어함으로써 사람처럼 스마트폰 앱과 상호작용하도록 구현하였다고 언급한다.

시스템 백엔드 접근이 불필요하며 GUI 수준에서 작동하기 때문에 앱 인터페이스의 변경이나 업데이트와 상관없이 유연하게 작동할 수 있다는게 해당 시스템의 장점이라고 한다.

Exploration Phase 실행 및 느낀점

그래서 위에서 언급한 목표를 달성하기 위해 논문에서 제시한 핵심 아이디어가 "document-driven few shot learning"이다.

인간이 새로운 앱을 빠르게 배우는 방식에서 영감을 받은 아이디어로, 에이전트는 앱과 상호작용하며 그 결과를 JSON 문서로 기록하고 학습한다.

에이전트는 스크린샷과 XML 정보를 받아, 화면에 어떤 버튼이 있고 어떤 요소가 클릭 가능한지를 스스로 파악한 뒤, 그 결과를 JSON 기반 문서(documentation) 로 기록하면서 학습한다.
이 문서는 이후 Deployment Phase에서 실제 명령을 수행할 때 일종의 “행동 지식 베이스”로 사용된다.

사실 이 논문을 읽을 수록 새로운 어플리케이션 UI 사용성 평가를 제외하곤 어떤 방향으로 해당 기술을 사용할 수 있을지 의문이 들었지만 시스템이 학습하는 Exploration Phase를 실행시켜보는 것은 상당히 재미있었다.

파일을 실행하면 2가지 모드가 뜬다.

Autonomous Exploration	에이전트가 스스로 UI를 탐색하며 상호작용. 각 행동의 결과를 문서로 기록
Human Demonstration	사용자가 직접 조작하면, 에이전트가 이를 관찰하고 문서화함

두 모드 모두 목표(Task Description)를 기반으로 진행된다.
예를 들어 이번 실험에서는 다음과 같은 명령을 주었다.

"execute YouTube and search dog video",
"Set an alarm for 12:30 PM every Friday and Sunday"

흠.. XML파일을 기반으로 UI를 인식한다고?

기본적으로 내가 이 시스템에 회의적이게 된 이유는 초반 시작할 때 해당 화면의 xml파일을 받아온다는 점이다.

AppAgent는 실시간 스크린샷과 함께, UI 요소에 대한 세부 정보를 담은 XML 파일을 입력으로 활용한다.

위 사진은 AppAgent가 Autonomous Exploration을 실행한 후에 생성된 파일들의 스크린샷인데 숫자는 turn 순서를 나타내고 before는 해당 턴 실행 전의 스크린샷, after는 해당 턴 실행 후의 스크린샷이다.

그리고 함께 xml 파일이 저장된 것을 볼 수 있다.

파일 내부에는 각 UI 요소의 위치(bounds), 속성(clickable, text, class 등), 계층 구조가 포함되어 있다.

XML 파일 예시

예를 들어,
<node class="android.widget.TextView" text="YouTube" clickable="true" bounds="[811,1400][1016,1672]" /> 이런 식으로 앱 내의 각 뷰(View)가 구체적으로 정의된다.

이를 통해 LLM은 “어떤 요소가 클릭 가능한지”, “이 좌표가 무엇을 의미하는지”를 시스템적으로 파악할 수 있다.

이것을 보고 내가 가졌던 의문은 "UI 내부구조를 이미 알고 잇따면 사실상 LLM이 완전한 시각적 추론을 하는 것은 아닐 수도 있지 않을까?"였다.

즉 논문에서 언급했듯이 사라이 눈으로 보고 판단하듯 시각적으로 행동하는 것이 아니라, 시스템이 이미 제공하는 UI정보에 의존해 조작하는 방식이기 때문에, 'GUI를 직접 이해한다'는 의미의 노벨티가 다소 약해 보였다.

게다가 현재 이 시스템은 아래 명령어로 XML 구조를 손쉽게 덤프해오고 있는데, iOS에서는 이런 구조를 손쉽게 덤프하기 어려운 것으로 알고 있어, 현재 구조로는 안드로이드 환경에 특화된 프레임워크라는 한계도 있어 보인다.

adb shell uiautomator dump

스크린샷 위 라벨 표시

저장된 png 파일 목록을 보면 labeled 라는 표시도 보일 것이다.

AppAgent는 스크린샷을 찍은 후 아래 사진처럼 UI에 라벨을 달아 표시하고 이를 LLM input으로 사용한다.

labeled 예시1

labeled 예시2

AppAgent는 스크린샷을 단순 저장하는 것이 아니라, 각 UI 요소에 번호(라벨)를 부여해 시각적으로 표시한다.

png 파일을 열어보면 UI의 클릭 가능한 요소마다 숫자가 붙어 있는 걸 볼 수 있다.

예를 들어 YouTube 앱에서는 “홈(1)”, “검색창(2)”, “프로필(3)” 이런 식으로 표시된다.

이 라벨링된 이미지는 LLM의 입력으로 들어가며, 모델은 “tap(5)”, “text(2): dog video”와 같은 형식으로 행동을 추론한다.

이는 단순한 스크린샷이 아니라 행동 가능한 상태 표현(actionable representation) 이라는 점에서 인상적이었다.

그러나 앞서 언급한 XML파일을 기반으로 한 라벨링 문제 때문에 아래 사진처럼 모달창의 경우 라벨링이 되지 않는 문제가 발생하기도 했다.

Explanation Phase 동작 과정

AppAgent는 이러한 input data를 바탕으로 LLM과 상호작용하며 해당 결과를 기록하고 사용자가 명령한 동작을 성공적으로 학습하기 위한 시행착오를 반복하며 학습해 나간다.

지원하는 task 종류는 다음과 같다.

유형	설명
앱 실행	홈 화면에서 유튜브 앱 실행
탭 동작 (tap)	라벨된 UI 요소에 한정
텍스트 입력 (text)	검색창에 "dog video" 입력 등
스크롤 (swipe)	1차 테스트에서 사용안함
long press	1차 테스트에서 사용안함
UI 뒤로가기(Back)	1차 테스트에서 사용안함
프로세스 종료(Exit)	1차 테스트에서 사용안함

Human Demonstration의 경우 아래처럼 인간과 상호작용하면서 어떻게 동작하는지를 학습하고 JSON을 담은 txt 파일을 생성해낸다.

아래는 실행한 terminal 기록 복사본이다.

Choose one of the following actions you want to perform on the current screen:
tap, text, long press, swipe, stop

tap
Which element do you want to tap? Choose a numeric tag from 1 to 13:

5
Choose one of the following actions you want to perform on the current screen:
tap, text, long press, swipe, stop

tap 
Which element do you want to tap? Choose a numeric tag from 1 to 13:

5
Choose one of the following actions you want to perform on the current screen:
tap, text, long press, swipe, stop

text
Which element do you want to input the text string? Choose a numeric tag from 1 to 3:

2
Enter your input text below:

dog video
Choose one of the following actions you want to perform on the current screen:
tap, text, long press, swipe, stop

tap
Which element do you want to tap? Choose a numeric tag from 1 to 6:

5
Choose one of the following actions you want to perform on the current screen:
tap, text, long press, swipe, stop

stop
Demonstration phase completed. 5 steps were recorded.

Human demonstration 결과물

Autonomous Exploration은 위 과정을 시스템이 LLM과 직접 상호작용하며 진행한다.

아래는 최종결과로 만들어진 text파일 복사본이다.

{"step": 1, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "1_before_labeled.png", "response": "Observation: The screenshot shows a smartphone home screen with various app icons. The clock app is labeled with the number 9.\n\nThought: To set an alarm, I need to open the clock app.\n\nAction: tap(9)\n\nSummary: I tapped the clock app icon to open it and proceed with setting an alarm."}
{"step": 2, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the clock app icon to open it and proceed with setting an alarm.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "2_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Wednesday, Thursday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday, I need to deselect Wednesday and Thursday, and select Friday. Then, I need to disable the vibration.\n\nAction: tap(14)\n\nSummary: I tapped the clock app icon to open it and proceeded with setting an alarm. I then selected Friday for the alarm."}
{"step": 3, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the clock app icon to open it and proceeded with setting an alarm. I then selected Friday for the alarm.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "3_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Wednesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to disable the vibration for the alarm.\n\nAction: tap(18)\n\nSummary: I tapped the clock app icon to open it, proceeded with setting an alarm, selected Friday, and then disabled the vibration."}
{"step": 4, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the clock app icon to open it, proceeded with setting an alarm, selected Friday, and then disabled the vibration.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "4_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Wednesday, Thursday, Friday, and Saturday. Vibration is disabled. The days of the week are selectable.\n\nThought: To complete the task, I need to deselect Wednesday and Thursday, leaving only Friday and Sunday selected.\n\nAction: tap(11)\n\nSummary: I tapped the clock app icon to open it, proceeded with setting an alarm, selected Friday, disabled the vibration, and deselected Wednesday."}
{"step": 5, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "5_before_labeled.png", "response": "Observation: The screen shows an alarm set for 12:30 PM on Sunday, Tuesday, Wednesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday only, I need to disable the other days. I will start by disabling Tuesday.\n\nAction: tap(11)\n\nSummary: I tapped to disable the alarm on Tuesday, leaving it set for Sunday, Wednesday, Thursday, Friday, and Saturday."}
{"step": 6, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "6_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday only, I need to deselect Tuesday, Thursday, and Saturday.\n\nAction: tap(10)\n\nSummary: I tapped to deselect Tuesday from the alarm schedule."}
{"step": 7, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped to deselect Tuesday from the alarm schedule.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "7_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Monday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to disable the vibration option.\n\nAction: tap(16)\n\nSummary: I tapped to deselect Tuesday from the alarm schedule and then disabled the vibration option."}
{"step": 8, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "8_before_labeled.png", "response": "Observation: The screen shows an alarm set for 12:30 PM on Sunday, Monday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday only, I need to deselect Monday, Tuesday, Thursday, and Saturday.\n\nAction: tap(10)\n\nSummary: I tapped to deselect Monday from the alarm schedule."}
{"step": 9, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped to deselect Monday from the alarm schedule.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "9_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to disable the vibration option.\n\nAction: tap(8)\n\nSummary: I tapped to deselect Monday from the alarm schedule and then disabled the vibration option."}
{"step": 10, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "10_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Tuesday, Thursday, Friday, and Saturday. Vibration is enabled.\n\nThought: To set the alarm for Friday and Sunday only, I need to deselect Tuesday, Thursday, and Saturday. I'll start by deselecting Tuesday.\n\nAction: tap(9)\n\nSummary: I tapped to deselect Tuesday from the alarm schedule."}
{"step": 11, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "11_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Monday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday only, I need to deselect Monday, Tuesday, Thursday, and Saturday. I will start by deselecting Monday.\n\nAction: tap(8)\n\nSummary: I observed that the alarm is set for multiple days, including Monday. I tapped to deselect Monday."}
{"step": 12, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I observed that the alarm is set for multiple days, including Monday. I tapped to deselect Monday.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "12_before_labeled.png", "response": "Observation: The alarm is set for multiple days: Monday, Tuesday, Thursday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to deselect Tuesday and Thursday, and disable the vibration.\n\nAction: tap(9)\n\nSummary: I deselected Monday. Now, I have deselected Tuesday to set the alarm for Friday and Sunday only."}
{"step": 13, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I deselected Monday. Now, I have deselected Tuesday to set the alarm for Friday and Sunday only.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "13_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Monday, Tuesday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to disable the vibration option.\n\nAction: tap(13)\n\nSummary: I deselected Monday and Tuesday to set the alarm for Friday and Sunday only. Now, I have disabled the vibration option."}
{"step": 14, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "14_before_labeled.png", "response": "```plaintext\nObservation: The screen shows the \"Alarm sound\" settings with options to select different sounds. There is a back button labeled 1.\nThought: To set the alarm, I need to go back to the main alarm settings screen.\nAction: tap(1)\nSummary: I tapped the back button to return to the main alarm settings screen to continue setting the alarm.\n```"}
{"step": 15, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the back button to return to the main alarm settings screen to continue setting the alarm.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "15_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Monday, Tuesday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To complete the task, I need to disable the vibration option.\n\nAction: tap(12)\n\nSummary: I tapped the back button to return to the main alarm settings screen and then disabled the vibration option for the alarm."}
{"step": 16, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "16_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Monday, Tuesday, Friday, and Saturday. The vibration option is enabled.\n\nThought: To set the alarm for Friday and Sunday, I need to deselect Monday and Tuesday, and select Sunday. Then, I need to disable the vibration.\n\nAction: tap(8)\n\nSummary: I tapped to deselect Monday from the alarm settings."}
{"step": 17, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped to deselect Monday from the alarm settings.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "17_before_labeled.png", "response": "```plaintext\nObservation: The alarm is set for 12:30 PM on Sunday, Monday, Tuesday, Friday, and Saturday. The vibration option is enabled.\nThought: To complete the task, I need to disable the vibration option.\nAction: tap(6)\nSummary: I tapped to deselect Monday from the alarm settings and then disabled the vibration option.\n```"}
{"step": 18, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: None\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "18_before_labeled.png", "response": "Observation: The screenshot shows a smartphone home screen with various app icons. The clock app is labeled with the number 9.\n\nThought: To set an alarm, I need to open the clock app.\n\nAction: tap(9)\n\nSummary: I tapped the clock app icon to open it and proceed with setting an alarm."}
{"step": 19, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the clock app icon to open it and proceed with setting an alarm.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "19_before_labeled.png", "response": "Observation: The screen shows the alarm section of a clock app. There are three alarms set: 8:30 AM, 9:00 AM, and 12:30 PM. The 12:30 PM alarm is active and set for Sunday, Monday, Tuesday, Friday, and Saturday. There is a toggle switch next to each alarm.\n\nThought: To set the 12:30 PM alarm for only Friday and Sunday, I need to edit the days it is set for.\n\nAction: tap(16)\n\nSummary: I tapped the clock app icon to open it and proceeded to tap the 12:30 PM alarm to edit its settings."}
{"step": 20, "prompt": "You are an agent that is trained to complete certain tasks on a smartphone. You will be \ngiven a screenshot of a smartphone app. The interactive UI elements on the screenshot are labeled with numeric tags \nstarting from 1. \n\nYou can call the following functions to interact with those labeled elements to control the smartphone:\n\n1. tap(element: int)\nThis function is used to tap an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be tap(5), which taps the UI element labeled with the number 5.\n\n2. text(text_input: str)\nThis function is used to insert text input in an input field/box. text_input is the string you want to insert and must \nbe wrapped with double quotation marks. A simple use case can be text(\"Hello, world!\"), which inserts the string \n\"Hello, world!\" into the input area on the smartphone screen. This function is only callable when you see a keyboard \nshowing in the lower half of the screen.\n\n3. long_press(element: int)\nThis function is used to long press an UI element shown on the smartphone screen.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen.\nA simple use case can be long_press(5), which long presses the UI element labeled with the number 5.\n\n4. swipe(element: int, direction: str, dist: str)\nThis function is used to swipe an UI element shown on the smartphone screen, usually a scroll view or a slide bar.\n\"element\" is a numeric tag assigned to an UI element shown on the smartphone screen. \"direction\" is a string that \nrepresents one of the four directions: up, down, left, right. \"direction\" must be wrapped with double quotation \nmarks. \"dist\" determines the distance of the swipe and can be one of the three options: short, medium, long. You should \nchoose the appropriate distance option according to your need.\nA simple use case can be swipe(21, \"up\", \"medium\"), which swipes up the UI element labeled with the number 21 for a \nmedium distance.\n\nThe task you need to complete is to set an alarm at 12:30 pm every Friday and Sunday, disable the vibration. Your past actions to proceed with this task are summarized as \nfollows: I tapped the clock app icon to open it and proceeded to tap the 12:30 PM alarm to edit its settings.\nNow, given the following labeled screenshot, you need to think and call the function needed to proceed with the task. \nYour output should include three parts in the given format:\nObservation: <Describe what you observe in the image>\nThought: <To complete the given task, what is the next step I should do>\nAction: <The function call with the correct parameters to proceed with the task. If you believe the task is completed or \nthere is nothing to be done, you should output FINISH. You cannot output anything else except a function call or FINISH \nin this field.>\nSummary: <Summarize your past actions along with your latest action in one or two sentences. Do not include the numeric \ntag in your summary>\nYou can only take one action at a time, so please directly call the function.", "image": "20_before_labeled.png", "response": "Observation: The alarm is set for 12:30 PM on Sunday, Monday, Tuesday, Friday, and Saturday. The vibration option is currently enabled.\n\nThought: To complete the task, I need to disable the vibration option.\n\nAction: tap(6)\n\nSummary: I tapped the clock app icon to open it, proceeded to tap the 12:30 PM alarm to edit its settings, and then disabled the vibration option."}

AppAgent의 프롬프트 설계

하지만 이 연구에서 참고하면 좋을 듯한 부분은 개인적으로 프롬프트 설계였다.

위 시스템에서는 여러 개의 프롬프트를 사용하였는데 그중 가장 인상적이었던 2장의 프롬프트를 소개하려 한다.

먼저 첫 번째 프롬프트이다.

프롬프트를 보면 주어진 스크린샷과 XML 라벨 정보를 바탕으로 Observation -> Thought -> Action -> Summary의 과정을 반복하는 것을 확인할 수 있다.

이때 각 행동의 목적을 요약하는 Summary까지 생성하여 행동 맥락을 지속적으로 확인하는 것을 관찰할 수 있다.

두 번째 프롬프트는 앞서 수행한 행동이 실제로 task를 진전시켰는지 판단한다.

두 장의 스크린샷(before/after)을 비교하여 다음 네 가지 중 하나를 결정한다.

BACK	잘못된 페이지로 이동함 → 이전 화면으로 복귀
INEFFECTIVE	아무 변화 없음
CONTINUE	변화는 있으나 목표와 무관
SUCCESS	목표를 향해 과업이 진전됨

이 평가 결과는 다시 문서(JSON)로 기록되어 이후 few-shot learning의 레퍼런스로 사용된다.
즉, AppAgent는 “관찰 → 행동 → 평가”의 완전한 순환 구조를 통해 스스로 탐색하고 개선하는 셈이다.

여기서 우리는 AppAgent가 Chain-of-Thought를 ‘행동 단위’로 확장한 시스템이라는 것을 알 수 있다.
텍스트로 사고 과정을 설명하는 수준을 넘어, 그 사고 결과를 실제 터치·입력·스와이프 같은 물리적 행동으로 연결한다.

물론 여전히 XML 기반 입력과 제한된 인터페이스 등 기술적 한계가 존재하지만, 이 구조는 “스스로 생각하고, 실수하고, 수정하는” LLM기반 행동 Agent의 가능성을 명확히 보여준다.

정리하며..

사실 딥러닝, 머신러닝 모델을 사용하는 것도 아니고 단순히 LLM API만 사용해서 이러한 시스템을 구현하였기 때문에 성능에 대한 기본적인 한계는 존재할 것이다.

실제로 실행해보며 나도 이점을 느꼈다.

하지만 해당 시스템에서 사용한 프롬프트를 보고 전체적인 동작 코드를 뜯어보면서 사람처럼 배워서 동작을 수행하는 agent를 만들겠다는 인간 모방 에이전트를 LLM과 프롬프트만으로는 꽤 잘 구현하지 않았나 생각한다.

기술적으로 업그레이드 된 AppAgentX에 대한 논문도 최근에 나왔으니 참고해보면 좋을 것 같다.

https://appagentx.github.io/

AppAgentX: Evolving GUI Agents as Proficient Smartphone Users

appagentx.github.io

https://arxiv.org/abs/2503.02268

AppAgentX: Evolving GUI Agents as Proficient Smartphone Users

Recent advancements in Large Language Models (LLMs) have led to the development of intelligent LLM-based agents capable of interacting with graphical user interfaces (GUIs). These agents demonstrate strong reasoning and adaptability, enabling them to perfo

arxiv.org

[Kotlin] 기본 문법 1 - 변수 및 자료형, 조건문, Array

orieasy1 — Sun, 12 Oct 2025 23:37:56 +0900

* 3학년 2학기 모바일 프로그래밍 수업 기록

현재 Android 어플리케이션을 개발하기 위해 주로 사용되는 언어는 바로 Kotlin이다.

Android 모바일 어플리케이션 개발 기록을 기록하기 앞서 Kotlin 문법에 대해 간단히 설명해보고자 한다.

(이 글은 기본적으로 Java를 알고 있다고 가정하고 정리한 글이다.)

1. 자료형

자료형은 다른 프로그래밍 언어와 매우 비슷하다.

숫자 자료형은 아래 이미지와 같다.

Boolean 자료형은 true와 false 두 가지 자료형을 포함하고 있다.

Charater은 Char타입으로 나타내는데 보통 ' '안에 작성한다.

특수 문자는 \(백슬래시)로 시작한다.

사용가능한 이스케이프 문자 목록은 아래와 같다.

\t (탭)
\b (백스페이스)
\n (줄바꿈)
\r (캐리지 리턴)
\' (작은따옴표)
\" (큰따옴표)
\\ (역슬래시)
\$ (달러 기호)

또한 다른 문자를 표현하려면 유니코드 이스케이프를 사용한다. (예: '\uFF00’)

다음은 String template이다.

문자열 템플릿이란 문자열 안에 변수나 식을 직접 삽입할 수 있는 기능을 말한다.

문자와 변수를 다로 연결할 필요없이 $기호를 사용해 간단하게 작성할 수 있다.

// 변수 이름 직접 삽입
val i = 0
println("i =$i")  // 출력: i = 10

//{}안에 expression 삽입
val s = "abc"
println("$s length is ${s.length}")  // 출력: abc length is 3

기본적으로 Kotlin에서 변수를 선언할 때는 var 키워드를 사용한다.

var 키워드를 사용해 선언한 변수는 재할당이 가능하다.

한 가지 Java와 다른 점은 타입 자동 추출이 가능하다는 것이다.

var x = 5 // Int로 타입이 자동으로 추출
x += 1

//자료형을 정의하면서 변수를 선언할 수 도 있다.
var y: Int

반면 상수는 val 키워드를 사용하여 선언한다.

읽기 전용이며 var과 달리 재할당이 불가능하다는 것이 특징이다.

val a: Int = 1    // 즉시 할당, 타입을 명시해서 선언할 수 있다.
val b = 2    // Int 타입이 자동으로 추론됨
val c: Int   // 초기값이 없으면 타입을 반드시 명시해야 함
c = 3   // 처음 한 번만 할당 가능, 두번째 할당은 불가능

2. 조건문

if 문

if문의 기본구조는 다른 언어와 유사하다.

// 기본 구조
if (조건) {
    // 조건이 true일 때 실행
}

// if ~ else
if (a > b) {
    max = a
} else {
    max = b
}

한 가지 다른 점은 kotlin에서 if는 값을 반환할 수 있는 표현식이기 때문에 변수에 바로 넣어서 사용할 수 있다는 것이다.

val max = if (a > b) a else b

위 식에서 표현되어있는 조건에 따라 그 결과 값이 max에 할당되게 됩니다.

Java와 C언어의 삼항 연산자 (a > b ? a : b)와 같은 역할을 한다.

아래 코드 처럼 여러 줄로 블럭을 작성하는 것 또한 가능하다.

val max = if (a > b) {
    println("Choose a")
    a   // 마지막 줄이 반환됨
} else {
    println("Choose b")
    b
}

2. when 문

Kotlin에만 존대하는 조건문이 있는데 그것이 바로 when문이다.

다른 언어에도 비슷한 문법(switch-case 등)은 존재하지만 when이라는 이름과 형태는 Kotlin의 고유 형태이다.

when문이 switch-case보다 더 강력하고 유연하다는 것이 특징이다.

여러 조건을 분기 처리할 때 사용하며, 값 비교뿐만 아니라 범위, 타입 검사 등 다양한 조건을 처리할 수 있다.

기본적인 구조는 다음과 같다.

// 기본구조
when(parameter) {
	condition -> action1
    condition -> action2
    
    else -> { //Note the block
    	action3
    }
}

// 예시
val grade = "A+"

when(grade){
	"A+" -> Log.d("ITM", "Oh.. great..!")
    "B+" -> Log.d("ITM", "Hey?")
    else -> {
    	 Log.d("ITM", "I don't know who you are")
    }
}

또 여러 조건을 ,로 묶어서 한 줄에 처리하는 것도 가능하다.

// 기본 구조
when (parameter) {
	condition1, condition2 -> action1
    else -> {// Note the block
    	action2
    }
}

// 예시
when (grade) {
    "A+", "B+", "C+" -> Log.d("ITM", "Oh.. great..!!")
    "A", "B", "C"    -> Log.d("ITM", "Hey?")
    else -> Log.d("ITM", "I don't know who you are.")
}

범위(Range)와 조건을 when문에서 활용할 수 있는데,

in 혹은 !in을 사용해 값이 특정 범위에 속하는지 검사가 가능하다.

val score = 89

when (score) {
	in 90..100 -> Log.d("ITM", "A+")
    else -> Log.d("ITM", "resit!")
}

또 parameter가 없는 when문은 if-else if 체인의 대체로 사용가능하다.

val score = 49

when {
	score > 90 -> Log.d("ITM", "A+")
    score in 50..89 -> Log.d ("ITM", "A0")
    else -> Log.d("ITM", "resit!!")
}

is 키워드를 사용하면 타입 체크도 가능하다.

val x: Any = 20.5

when (x) {
	is Int -> Log.d("It's Int type")
    is String -> Log.d("It's String type")
    else -> Log.d("What is this?")
}

when문이 Java의 조건문과 비교했을 때 특별한 점은 단순한 제어문이 아니라 표현식으로도 사용할 수 있다는 점이다.

즉 값을 반환하여 변수에 할당할 수 있다.

val myScore = 80
val myGrade = when(myScore) {
	in 90..100  -> "A+"
    else -> "F"
}

Log.d("ITM, "My score is $myScore, so my grade is $myGrade")

3. Array 배열

배열은 기본적으로 고정 길이 데이터를 저장하는 자료구조로 한 번 크기를 정하면 변경할 수 없는 것이 특징이다.

다른 언어와 마찬가지로 인덱스(0부터 시작)으로 접근한다.

초기화 방법은 크게 2가지로 볼 수 있다.

먼저 Array()을 사용하여 크기를 지정하여 생성하는 경우가 있고, 두 번째로 arrayOf()를 사용하여 직접 값을 넣어 생성하는 경우가 있다.

// Array() 생성자: 크기, 초기화 함수
val squares = Array(5) { i -> i * i}
// 결과: [ 0, 1, 4, 9, 16]

//arrayOf(): 요소 직접 지정
val fruits = arrayOf("apple", "banana", "cherry")

Kotlin은 성능을 위해 각 기본형에 맞는 배열 타입을 제공한다.

배열 종류에는 ByteArray, ShortArray, IntArray, LongArray, CharArray, FloatArray, DoubleArray, BooleanArray가 있다.

val x: IntArray = intArrayOf(1,2,3)
var y = arrayOf("one", two","three")

val arr = IntArray(5)
// 결과: [0, 0, 0, 0, 0]

var arr2 = IntArray(5) { 42 }
// 결과: [42, 42, 42, 42, 42]

var arr3 = IntArray(5) { it + 1 }
// 결과: [1, 2, 3, 4, 5]

var arr4 = Array(5){i -> i * i}
// 결과: [0, 1, 4, 9, 16]

get(), set() 또는 [ ] 연산자를 사용하여 값에 접근할 수 있다.

동작	문법	설명
조회	arr[index]	특정 위치의 값 읽기
조회2	arr.get(index)	get() 함수 사용
변경	arr[index] = value	인덱스로 값 변경
변경2	arr.set(index, value)	set() 함수 사용

자주 쓰는 유틸리티 함수는 다음과 같다.

함수	설명
size	배열의 크기 반환
first() / last()	배열의 첫/마지막 요소 반환
sort()	오름차순 정렬 (원본 변경됨)
sortedArray()	정렬된 새 배열 반환
sortedArrayDescending()	내림차순 정렬된 새 배열 반환

val x: IntArray = intArrayOf(1, 2, 3) 
val y = arrayOf("one", "two", "three")
val arr = IntArray(5) 
val arr2 = IntArray(5) { 42 } 
var arr3 = IntArray(5) { it+1 }
var arr4 = Array(5){i-> i*i}

Log.d("ITM","x.size: ${x.size}")
Log.d("ITM","arr.size: ${arr.size}")

Log.d("ITM",Arrays.toString(x))
Log.d("ITM",Arrays.toString(y))
Log.d("ITM",Arrays.toString(arr))
Log.d("ITM",Arrays.toString(arr2))
Log.d("ITM",Arrays.toString(arr3))
Log.d("ITM",Arrays.toString(arr4))

val arr: IntArray = IntArray(10){it+1}
val first = arr[0]
val first2 = arr.first()
val first3 = arr.get(0)
val last = arr.last()

Log.d("ITM", "${Arrays.toString(arr)}")
Log.d("ITM", "first: $first $first2 $first3 last: $last")

arr[0] = 100
arr.set(1,200)

Log.d("ITM", "${Arrays.toString(arr)}")
arr.sort() // in-place sorting
val arr2 = arr.sortedArrayDescending() // return a new sorted array (desc.)

Log.d("ITM", "${Arrays.toString(arr)}")
Log.d("ITM", "${Arrays.toString(arr2)}")

Chrome 확장 프로그램과 Node.js 서버 간 WebSocket 통신 구축 방법

orieasy1 — Sun, 5 Oct 2025 15:40:13 +0900

지난 여름, 연구실에서 사용자 적응형 다크 모드 프로그램과 관련해서 연구를 진행했었습니다.

~~엎어졌지만...~~

그때 구상했던 전체 시스템 아키텍처의 경우, 클라이언트에서 서버로 요청을 보내서 수정 및 구현을 하는게 아니라 서버에서 클라이언트로 요청을 보내 서버의 요청대로 클라이언트에서 수정을 진행해주어야 했습니다.

그 말인 즉슨 HTTP 요청 - 응답 구조만으로는 한계가 있음을 의미합니다.

1. HTTP의 한계와 WebSocket의 사용

전통적인 웹통신 구조인 HTTP 요청-응답 모델은 항상 "클라이언트가 요청 → 서버가 응답" 하는 단방향 구조를 가지고 있습니다.

이 방식은 일반적인 웹사이트나 API 요청에는 충분하지만 제가 구상했던 사용자 적응형 다크 모드 시스템 처럼 서버가 클라이언트의 상태를 제어해야하는 구조에는 적합하지 않았습니다.

예를 들어, 서버가 전달받은 정보를 바탕으로 "지금 사용자의 화면 밝기를 낮춰야겠다"는 판단을 내렸다고 합시다.

HTTP 기반 구조라면 서버는 클라이언트가 요청을 보내기 전까지는 아무것도 할 수 없습니다.

서버가 먼저 행동을 지시해야하는데 HTTP의 경우 서버가 먼저 행동을 '지시'할 수 있는 방법이 없는 것이죠.

이런 문제를 해결하기 위해 사용할 수 있는 것이 바로 양방향 통신인 WebSocket입니다.

WebSocket이란?

WebSocket은 클라이언트와 서버가 항상 연결된 상태로 실시간 양방향 통신을 주고 받을 수 잇는 프로토콜입니다.

한 번의 handshake 이후에는 서버가 언제든 클라이언트로 메세지를 보낼 수 있고, 클라이언트 역시 별도의 요청 없이 데이터를 즉시 서버에 보낼 수 있습니다.

즉 WebSocket을 사용하면, 요청에만 반응하는 웹의 기존 패러다임에서 벗어나 지속적이고 상호적인 연결을 구축할 수 있습니다.

	HTTP	WebSocket
연결 구조	요청 후 응답으로 종료	한 번 연결 후 지속 유지
통신 방향	단방향 (client → server)	양방향 (client ↔ server)
사용 예시	일반 API, 데이터 요청	채팅, 알림, 실시간 제어
전송 프로토콜	HTTP/HTTPS	ws:// 또는 wss://

그래서 저는 이 WebSocket 통신을 이용하여 서버가 클라이언트에게 "폰트 크기를 조정해라, "화면의 대비를 키워라" 등의 명령을 전달하면 클라이언트에서 해당 내용을 실시간으로 적용하는 시스템을 구상했습니다.

2. 시스템 설명 및 구현

2.1 전체 시스템 구상

다시 한 번 설명하자면, (음.. 여기서 주제 관련 자세한 이야기는 할 수 없지만...) 구상한 시스템 아키텍처 상 서버가 클라이언트를 제어하는 구조여야 했고, 이를 위해서는 WebSocket 통신을 도입하는 방향으로 진행을 해야했습니다.

Chrome Extension으로 해당 시스템을 만들어야 했고 Chrome Extension은 대부분 TypeScript로 이루어져있습니다.

그래서 JavaScript를 사용하는 Backend Framework인 Node.js로 서버를 구축하고 Chrome Extension의 background.ts를 클라이언트로 설정해 서버에서 직접 확정 프로그램 UI를 제어하는 구조를 시도 했습니다.

그 과정에서 CSP, popup 제약 등 여러 시행착오를 겪었지만, 결국 background 기반 WebSocket 통신이 가장 안정적이라는 결론에 도달 했습니다.

2.2 왜 background.ts?

왜 background에서 WebSocket 통신으 다루는 것이 안정적인지에 대한 이야기를 해보겠습니다.

Chroem 확장 프로그램은 크게 3가지 주요 실행 단위로 구성됩니다.

	설명	실행 특성
popup	사용자가 확장 아이콘을 클릭했을 때 뜨는 UI 화면	일시적 (UI 닫히면 종료)
content script	웹페이지에 삽입되어 DOM을 조작하는 스크립트	페이지 단위로 로드/종료
background	확장 프로그램 전체의 백엔드 로직을 담당하는 스크립트 (Service Worker 형태)

이 중 background는 말 그대로 확장 프로그램의 두뇌 역할을 합니다.

popup이 사라져도, 탭이 닫혀도 background는 살아남아 확장 전체의 상태를 관리하고 서버와의 연결을 유지합니다.

WebSocket의 핵심은 "한 번 연결되면 계속 살아있는 상태로 데이터를 주고받는 것"입니다.

하지만 popup이나 content script는 수명이 짧기 때문에 WebSocket 연결을 여기에 두면 다음과 같은 문제가 발생합니다.

popup을 닫으면 연결이 바로 끊김
페이지가 새로고침되면 연결이 초기화됨
백그라운드에서 서버의 메시지를 수신할 수 없음

또 추가적으로 Chrome Extension은 보안상 Content Security Policy(CSP)가 매우 엄격합니다.

그래서 Chrome Extension에서 WebSocket 연결은 항상 실행중인 background에서 관리하고, 필요할 때 popup이나 content script와 메시지를 주고받는 구조가 제일 안정적인 것입니다.

2.3 기본 시스템 구조 설계 및 구현

그래서 제가 구상한 기본적인 시스템 구조는 다음과 같습니다.

[ Chrome Extension ]
     └─► background.ts
              └─ WebSocket 연결
              └─ 서버에 메시지 전송 / 수신 처리

[ Node.js Backend Server ]
     └─ WebSocket 서버 (ws://localhost:3001)
              └─ 메시지 수신 → 처리 → 응답 전송

초기 세팅 과정

벡엔드 폴더로 접속하여 아래 명령어를 실행해 필요한 기본 패키지를 설치했습니다.

npm install
npm install ws
npm install express

그리고 지금은 기본적인 부분만 구축했기 때문에 index.js 파일에서 WebSocket 통신을 관리하도록 기본 코드를 작성해놓앗습니다.

추후에는 node index.js 명령어로 서버를 실행할 수 있고 서버가 성공적으로 실행되면 대기중인 WebSocket 서버도 활성화됩니다.

서버 측 구현

아래 코드는 단순히 연결된 클라이언트의 메세지를 받아 같은 내용을 echo 형태로 되돌려주는 구조입니다.

index.js

const WebSocket = require('ws');

// WebSocket 전용 포트
const PORT = 3001;

// 서버 생성
const wss = new WebSocket.Server({ port: PORT });

wss.on('connection', (ws) => {
  console.log('✅ 클라이언트 WebSocket 연결됨');

  ws.on('message', (message) => {
    console.log('  클라이언트 메시지:', message.toString());

    // 응답 전송
    ws.send(`서버 응답: ${message}`);
  });

  ws.on('close', () => {
    console.log('❌ 클라이언트 연결 종료');
  });
});

console.log(`  WebSocket 서버 실행 중 (ws://localhost:${PORT})`);

하지만 추후에는 이부분에 다크모드 상태 업데이트 등의 사용자 환경 제어 명령을 추가할 수 있습니다.

클라이언트 측 구현 (background.ts)

아래 코드는 Chrome Extension의 background.ts 파일에서 WebSocket 클라이언트로 동작하도록 구현한 부분입니다.

저희는 다크 모드 관련 확장 프로그램인 DarkReader의 3.5.4 버전에서 수정을 실행했습니다.

아래 코드는 해당 확장 프로그램의 background.ts 파일에 추가한 내용입니다.

https://github.com/darkreader/darkreader

GitHub - darkreader/darkreader: Dark Reader Chrome and Firefox extension

Dark Reader Chrome and Firefox extension. Contribute to darkreader/darkreader development by creating an account on GitHub.

github.com

popup에서 직접 서버에 연결을 시도하면 CSP(Content Security Policy) 제약으로 차단되기 때문에, 항상 실행되는 background service worker가 서버와의 지속적인 연결을 담당하도록 설계했습니다.

// WebSocket 변수
let socket: any = null;

// WebSocket 연결 함수
function connectWebSocket() {
    socket = new WebSocket('ws://localhost:3001');

    socket.onopen = () => {
        console.log('[bg] WebSocket 연결됨');
        if (socket && socket.readyState === 1) {
            socket.send('[bg] 확장에서 서버 연결됨');
        }
    };

    socket.onmessage = (event) => {
        console.log('[bg] 서버 응답:', event.data);
        chrome.runtime.sendMessage({ from: 'server', data: event.data });
    };

    socket.onclose = () => {
        console.warn('[bg] 연결 끊김 → 재연결 예정');
        setTimeout(connectWebSocket, 3000);
    };

    socket.onerror = (err) => {
        console.error('[bg] WebSocket 오류:', err);
        if (socket) socket.close();
    };
}

// popup에서 보내는 메시지 수신 → 서버로 전달
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
    if (msg.from === 'popup' && socket && socket.readyState === 1) {
        console.log('[bg] popup → 서버:', msg.data);
        socket.send(msg.data);
    }
});

// 확장 프로그램 초기화 시 WebSocket 연결 실행
loadConfigs(() => {
    extension = new DarkReader.Extension(new DarkReader.FilterCssGenerator());
    onExtensionLoaded.invoke(extension);

    // WebSocket 연결 시작
    connectWebSocket();
});

3. 작동 확인

darkreader 3.5.4는 mainfest v2로 구버전입니다.

해당 버전으로 제작한 크롬 확장 프로그램은 더이상 크롬에서 지원해주지 않는다는 점을 참고해주시면 좋을 것 같습니다.

(제가 개발할 당시에는 아직까지 지원해주는 상태였고, 필요시에는 크롬을 다운그레이드하여 실행하기도 했습니다)

3.1 빌드 폴더 생성

먼저 확장 프로그램 코드를 빌드합니다.

아래 명령어를 실행하면 자동으로 build 폴더가 생성됩니다.

npm run release

빌드 과정에서 필요한 패키지가 없다는 에러가 뜬다면 npm이 안내하는 대로 추가 패키지들을 설치해 주세요.

저 명령을 실행한 후에 추가적으로 설치가 필요하다고 안내되면 저는 다 설치했던 것으로 기억합니다.

3.2 Chrome 확장 프로그램 등록

크롬 주소창에 chrome://extensions 를 입력해 확장 프로그램 관리 페이지로 이동합니다.

오른쪽 상단의 개발자 모드를 활성화합니다.

3.1 단계에서 생성된 build.zip을 압축 해제합니다.

확장 프로그램 관리 페이지에서 "압축해제된 확장 프로그램 로드" 버튼을 클릭하고 방금 압축 해제한 buil 폴더를 선택해 등록합니다.

아래 사진에 Dark Reader 3.5.4가 등록된 것 보이시죠?

등록이 완료되면 확장 프로그램이 크롬에 추가되고, 확장 아이콘을 통해 popup 화면을 열 수 있습니다.

3.3 백엔드 서버 실행 및 연결 확인

이제 WebSocket 서버를 실행해보겠습니다.

VS Code 터미널에서 backend 폴더로 이동한 뒤 아래 명령어를 입력합니다.

node index.js

정상적으로 실행되면 콘솔에 다음과 같은 로그가 출력됩니다:

  WebSocket 서버 실행 중 (ws://localhost:설정한 포트 번호)
✅ 클라이언트 WebSocket 연결됨

그리고 크롬 확장 프로그램 관리 페이지에서 아래 사진 속 뷰 검사 페이지(background/background.html)에 접속합니다.

아래 로그를 확인할 수 있다면 연결 성공입니다!

[bg] WebSocket 연결됨  
[bg] 서버 응답: [bg] 확장에서 서버 연결됨

WebSocket 통신 연결 성공 화면

4. 추가 화면 수정 로직 구현

앞서 작성한 코드에서 좀 더 수정하여 5초마다 랜덤한 다크모드 설정을 서버가 전송하고 확장 프로그램이 이를 받아 동적으로 적용하는 기능을 구현했습니다.

코드 구현

// index.js
const WebSocket = require('ws');

// WebSocket 전용 포트
const PORT = 3001;

// 서버 생성
const wss = new WebSocket.Server({ port: PORT });

wss.on('connection', (ws) => {
  console.log('✅ 클라이언트 WebSocket 연결됨');

  ws.on('message', (message) => {
    console.log('  클라이언트 메시지:', message.toString());

    // 응답 전송
    ws.send(`서버 응답: ${message}`);
  });

  // 5초마다 임의의 JSON 데이터 전송
  const intervalId = setInterval(() => {
    const data = {
      type: 'UPDATE_FILTER',
      payload: {
        mode: 1, // 다크모드
        brightness: Math.floor(Math.random() * 100) + 50,
        contrast: Math.floor(Math.random() * 100) + 50,
        grayscale: Math.floor(Math.random() * 100), // 0~99
        sepia: Math.floor(Math.random() * 100),     // 0~99
        useFont: Math.random() > 0.5,               // true/false 랜덤
        fontFamily: "Open Sans",                     // 예시 폰트
        textStroke: Math.floor(Math.random() * 3),   // 0~2
        invertListed: false,
        siteList: []
      }
    };
    console.log('서버가 전송하는 JSON:', data);
    ws.send(JSON.stringify(data));
  }, 5000);

  ws.on('close', () => {
    console.log('❌ 클라이언트 연결 종료');
    clearInterval(intervalId);
  });
});

console.log(`  WebSocket 서버 실행 중 (ws://localhost:${PORT})`);

// background.ts
// WebSocket 변수
    let socket: any = null;

    // WebSocket 연결 함수
    function connectWebSocket() {
        socket = new WebSocket('ws://localhost:3001');

        socket.onopen = () => {
            console.log('[bg] WebSocket 연결됨');
            if (socket && socket.readyState === 1) {
                socket.send('[bg] 확장에서 서버 연결됨');
            }
        };

        socket.onmessage = (event) => {
            try {
                const data = JSON.parse(event.data);
                if (data.type === 'UPDATE_FILTER') {
                    console.log('[bg] 서버에서 받은 UPDATE_FILTER payload:', data.payload);
                    // config를 동적으로 갱신 (Object.assign 대신 for...in 사용)
                    for (var key in data.payload) {
                        if (data.payload.hasOwnProperty(key) && extension.config.hasOwnProperty(key)) {
                            extension.config[key] = data.payload[key];
                        }
                    }
                    // 모든 탭에 스타일 적용
                    chrome.tabs.query({}, (tabs) => {
                        tabs.forEach(tab => {
                            if (tab.id && tab.url) {
                                extension["addStyleToTab"](tab); // protected이지만 강제 접근
                            }
                        });
                    });
                }
            } catch (e) {
                console.log('[bg] 서버 응답:', event.data);
            }
        };

        socket.onclose = () => {
            console.warn('[bg] 연결 끊김 → 재연결 예정');
            setTimeout(connectWebSocket, 3000);
        };

        socket.onerror = (err) => {
            console.error('[bg] WebSocket 오류:', err);
            if (socket) socket.close();
        };
    }

    // popup에서 보내는 메시지 수신 → 서버로 전달
    chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
        if (msg.from === 'popup' && socket && socket.readyState === 1) {
            console.log('[bg] popup → 서버:', msg.data);
            socket.send(msg.data);
        }
    });

    loadConfigs(() => {
        extension = new DarkReader.Extension(new DarkReader.FilterCssGenerator());
        onExtensionLoaded.invoke(extension);

        //websocket 연결
        connectWebSocket();
    });

작동 확인

브라우저 콘솔을 통해 전송된 JSON 데이터와 적용 결과를 모두 확인할 수 있었으며, 설정 값이 5초 간격으로 정상적으로 변경되고 반영되는 것을 확인했습니다.

[LangChain] 1. LangChain 시작하기: OpenAI API부터 Runnable까지

orieasy1 — Sat, 4 Oct 2025 23:41:57 +0900

※ Teddy님의 랭체인 노트 책을 바탕으로 진행하는 스터디 기록입니다.

해당 쳅터: LangChain 노트 Ch01

1. 기본 환경 설정 및 OpenAI API키 발급

우선 아래 링크 내용을 바탕으로 기본 환경 설정을 진행했고 OpeanAI 웹사이트에 접속하여 OpenAI API키 발급까지 진행했습니다.

https://teddynote.com/10-RAG%EB%B9%84%EB%B2%95%EB%85%B8%ED%8A%B8/%ED%99%98%EA%B2%BD%20%EC%84%A4%EC%A0%95%20(Mac)/

환경 설정 (Mac)

환경 설정 (Mac) 터미널 열기 spotlight 검색에서 "terminal" 검색 후 열기 Homebrew 설치 Homebrew 설치 명령어 1. 아래의 명령어를 실행하여 Homebrew 설치 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/

teddynote.com

2. LangSmith 추적 설정

LangSmith는 LLM 애플리케이션 개발, 모니터링 테스트를 위한 플랫폼입니다.

LLM 기반 애플리케이션을 개발하고 운영할 때 관찰성(obsevability), 평가(evaluation), 디버깅(debug), 모니터링(monitoring), 프롬프트 엔지니어링을 지합니다.

그중 가장 뒤어난 것은 추적 기능인데, 추적은 LLM 애플리케이션의 동작을 이해하기 위한 강력한 도구입니다.

추적 기능은 다음과 같은 문제를 추적하는데 도움을 줍니다.

1. 예상하지 못한 최종 결과

2. 에이전트가 루핑되는 이유

3. 체인이 예상보다 느린 이유

4. 에이전트가 각 단계에서 사용한 토큰 수

LangSmith를 사용하면 프로젝트 단위로 추적할 수 있고 각각의 실행에 대한 세부 단계별 추적도 가능하기 때문에 매우 편리합니다.

2.1 LangSmith 추적 기본 설정

우선 https://smith.langchain.com/으로 접속하여 회원가입을 진행합니다

이후 좌측 하단의 톱니바퀴를 눌러 설정으로 들어간 뒤 '+API Key' 버튼을 눌러 새로운 api 키를 발급 받습니다.

항상 새로운 api key를 생성하면 안전한 곳에 저장해두어야 합니다.

그리고 .env 파일을 만들어서 생성한 키들을 작성해줍니다.

.env 파일은 추후에 깃허브에 공유되지 않도록 꼭 .gitignore 파일을 만들어서 적어줍니다.

2.2 추적 활성화 하기

추적을 활성화하는 방법은 매우 간단한데, 환경 변수만 설정해주면 됩니다.

먼저 .env에 설정한 내용을 다음 코드를 불러옵니다.

from dotenv import load_dotenv

load_dotenv()

저의 경우에는 처음 이렇게 돌렸을 때 아래 사진처럼 ModuleNotFoundError가 떴습니다.

python-dotenv 모듈이 설치되어있지 않아 발생하는 에러로 아래 명령어를 입력해 모듈을 설치하면 해결할 수 있습니다.

pip install python-dotenv

우선은 책을 따라서 langchain-teddynote 패키지를 사용할 것이므로 아래 명령어를 터미널 창에서 실행해주었습니다.

pip install langchain-teddynote

.env 파일에 LangSmith 키를 설정해둔 상태로 아래 코드를 입력해서 실행합니다.

from langchain_teddynote import logging

# " "안에는 프로젝트 이름을 입력
logging.langsmith("CH01-Basic")

추적을 원하지 않을 때는 다음과 같이 추적을 끌 수 있습니다.

from langchain_teddynote import logging

# set_enable=False 로 지정하면 추적을 하지 않습니다.
logging.langsmith("랭체인 튜토리얼 프로젝트", set_enable=False)

3. OpenAI API 사용

LangChain의 핵심은 LLM을 객체처럼 다루면서 실행과 추적을 쉽게 만드는 것입니다.

ChatOpenAI 클래스는 OpenAI의 ChatAPI를 파이썬 객체로 감싸서, 복잡한 HTTP 요청 없이도 모델을 호출하고 응답을 다룰 수 있게 해줍니다.

3.1 기본 LLM 호출 - .invoke()

invoke()는 가장 단순한 실행 방식인데요, 하나의 프롬프트를 입력하면 LLM이 한 번에 전체 답변을 반환합니다.

from langchain_openai import ChatOpenAI

# 객체 생성
llm = ChatOpenAI(
    temperature=0.1,  # 창의성 (0.0 ~ 2.0)
    model_name="gpt-4.1-nano",  # 모델명
)

# 질의내용
question = "대한민국의 수도는 어디인가요?"

# 질의
print(f"[답변]: {llm.invoke(question)}")

[답변]: content='대한민국의 수도는 서울입니다.'

이처럼 .invoke()는 단일 입력을 동기식(synchronous) 으로 처리합니다.

즉, 모델이 응답을 모두 생성할 때까지 기다린 후 결과를 반환합니다.

LangChain은 이때 모델의 응답을 단순한 문자열이 아니라 AIMessage 객체로 감쌉니다.

이 객체에는 모델이 생성한 텍스트뿐 아니라 토큰 사용량, 모델명, 실행 ID 같은 추가적인 메타데이터가 함께 담겨 있습니다.

# 질의내용
question = "대한민국의 수도는 어디인가요?"

# 질의
response = llm.invoke(question)

response

AIMessage(content='대한민국의 수도는 서울입니다.', additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 8, 'prompt_tokens': 16, 'total_tokens': 24, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}, 'model_name': 'gpt-4.1-nano-2025-04-14', 'system_fingerprint': 'fp_7c233bf9d1', 'id': 'chatcmpl-CMxNoDvrYIsaDJr1mcSvs8FnfjtpI', 'service_tier': 'default', 'finish_reason': 'stop', 'logprobs': None}, id='run--ec12ab19-da5e-491f-9265-077114f22fd8-0', usage_metadata={'input_tokens': 16, 'output_tokens': 8, 'total_tokens': 24, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 0}})

response.content

'대한민국의 수도는 서울입니다.'

response.response_metadata

{'token_usage': {'completion_tokens': 8, 'prompt_tokens': 16, 'total_tokens': 24, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}, 'model_name': 'gpt-4.1-nano-2025-04-14', 'system_fingerprint': 'fp_7c233bf9d1', 'id': 'chatcmpl-CMxNoDvrYIsaDJr1mcSvs8FnfjtpI', 'service_tier': 'default', 'finish_reason': 'stop', 'logprobs': None}

3.2 스트리밍 출력 - .stream()

다음은 stream() 메서드를 활용해 토큰 단위로 실시간 출력을 받는 방식입니다.

대화형 챗봇이나 UI에서 “한 글자씩 출력되는” 효과를 구현할 때 사용합니다.

# 스트림 방식으로 질의
# answer 에 스트리밍 답변의 결과를 받습니다.
answer = llm.stream("대한민국의 아름다운 관광지 10곳과 주소를 알려주세요!")

# 스트리밍 방식으로 각 토큰을 출력합니다. (실시간 출력)
for token in answer:
    print(token.content, end="", flush=True)

실행하면 모델이 답변을 생성하는 즉시 토큰 단위로 출력됩니다. 화면에는 글이 점점 완성되는 형태로 나타납니다.

LangChain 내부적으로는 OpenAI의 Server-Sent Events (SSE) 방식을 사용하여

모델이 토큰을 생성할 때마다 즉시 전달받습니다.

따라서 stream()은 “대화형 UX를 구현할 때 반드시 알아야 할 핵심 함수”입니다.

3.3 멀티 모달 모델 - MultiModal()

멀티모달(Multi-Modal)은 텍스트뿐 아니라 이미지나 음성, 비디오 등 여러 형태의 데이터를 통합적으로 이해하고 처리하는 기술을 의미합니다.

텍스트: 문서, 책, 웹 페이지 등의 글자로 된 정보
이미지: 사진, 그래픽, 그림 등 시각적 정보
오디오: 음성, 음악, 소리 효과 등의 청각적 정보
비디오: 동영상 클립, 실시간 스트리밍 등 시각적 및 청각적 정보의 결합

LangChain에서는 MultiModal 객체를 통해 이미지를 입력으로 받아 LLM이 이를 해석하도록 할 수 있습니다.

from langchain_teddynote.models import MultiModal
from langchain_teddynote.messages import stream_response

# 객체 생성
llm = ChatOpenAI(
    temperature=0.1,  # 창의성 (0.0 ~ 2.0)
    model_name="gpt-4.1-nano",  # 모델명
)

# 멀티모달 객체 생성
multimodal_llm = MultiModal(llm)

# 샘플 이미지 주소(웹사이트로 부터 바로 인식)
IMAGE_URL = "https://t3.ftcdn.net/jpg/03/77/33/96/360_F_377339633_Rtv9I77sSmSNcev8bEcnVxTHrXB4nRJ5.jpg"

# 이미지 파일로 부터 질의
answer = multimodal_llm.stream(IMAGE_URL)
# 스트리밍 방식으로 각 토큰을 출력합니다. (실시간 출력)
stream_response(answer)

4. LCEL (LangChain Expression Language) 기본 개념

LangChain Expression Language, 줄여서 LCEL은 기존의 체인(LLMChain) 구조를 더 직관적이고 선언적으로 표현할 수 있도록 만든 문법입니다.

즉, “LLM 파이프라인을 코드가 아니라 수식처럼 표현” 할 수 있게 해주는 새로운 방식이에요.

기존에는 체인을 만들려면 긴 코드가 필요했지만 LCEL에서는 훨씬 간단하게 아래 한 줄로 표현할 수 있다.

chain = prompt | llm | parser

이 구조는 파이프(|) 연산자를 이용해 각 단계를 함수처럼 연결하는 선언형 구조입니다.

덕분에 체인을 작성할 때 “데이터의 흐름”이 한눈에 들어오죠.

4.1 LCEL의 기본 구조

LCEL은 크게 3가지 구성 요소로 이루어져있습니다.

구성요소	역할	예시 클래스
Prompt	입력을 문자열 템플릿으로 변환	ChatPromptTemplate
LLM	실제 모델 호출	ChatOpenAI
Parser	모델의 출력을 사람이 보기 좋은 형태로 변환	StrOutputParser

이 세 가지를 | 로 연결하면 완전한 체인이 만들어집니다.

4.2 LCEL 예시 코드

from langchain_teddynote.messages import stream_response
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

template = """
당신은 영어를 가르치는 10년차 영어 선생님입니다. 주어진 상황에 맞는 영어 회화를 작성해 주세요.
양식은 [FORMAT]을 참고하여 작성해 주세요.

#상황:
{question}

#FORMAT:
- 영어 회화:
- 한글 해석:
"""

# 프롬프트 템플릿을 이용하여 프롬프트를 생성합니다.
prompt = PromptTemplate.from_template(template)

# ChatOpenAI 챗모델을 초기화합니다.
model = ChatOpenAI(model_name="gpt-4.1-nano")

# 문자열 출력 파서를 초기화합니다.
output_parser = StrOutputParser()

# 체인을 구성합니다.
chain = prompt | model | output_parser

# 완성된 Chain을 실행하여 답변을 얻습니다.
answer = chain.stream({"question": "저는 식당에 가서 음식을 주문하고 싶어요"})
stream_response(answer)

5. LCEL Advanced

기본 LCEL(prompt | llm | parser)은 하나의 선형 체인만 구성하지만, LangChain은 LCEL을 Runnable 구조로 확장하여 “여러 체인을 병렬로 실행하거나, 순차적으로 연결”할 수 있게 합니다.

Runnable은 “실행 가능한 모든 노드”를 의미합니다.

즉, PromptTemplate, ChatOpenAI, StrOutputParser, 심지어 RunnableSequence까지 모두 Runnable로 취급됩니다.

Runnable은 표준화된 실행 인터페이스를 제공합니다.

메서드	동기/비동기	설명
invoke()	동기	입력 1건을 실행하고 최종 결과 반환
stream()	동기	토큰/청크 단위로 실시간 출력
batch()	동기	여러 입력을 병렬로 실행
ainvoke()	비동기	입력 1건을 비동기로 실행
astream()	비동기	토큰 단위 비동기 스트리밍
abatch()	비동기	여러 입력을 비동기로 실행
astream_log()	비동기	실행 중 발생하는 중간 단계를 실시간으로 로그 스트리밍

해당 메서드를 쓰는 상황은 아래와 같이 정리할 수 있습니다.

상황	추천 메서드	설명
단일 입력을 빠르게 처리	invoke()	가장 단순한 실행
대화형 실시간 출력	stream() 또는 astream()	스트리밍 토큰 출력
여러 입력을 한꺼번에 처리	batch() 또는 abatch()	대량 처리용
서버 환경의 비동기 파이프라인	ainvoke() / abatch()	asyncio 기반
디버깅, 로그 추적	astream_log()	중간 이벤트 추적
여러 체인을 병렬 실행	RunnableMap	병렬 분기 처리
단계별 순차 실행	RunnableSequence	단계적 파이프라인

5.1 기본 체인 - invoke / stream/ batch

stream: 실시간 토큰 단위 응답
invoke: 일반 동기 호출
batch: 여러 입력을 병렬 실행

from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 모델 및 체인 구성
model = ChatOpenAI()
prompt = PromptTemplate.from_template("{topic} 에 대하여 3문장으로 설명해줘.")
chain = prompt | model | StrOutputParser()

# 1️⃣ 실시간 스트리밍 실행
for token in chain.stream({"topic": "멀티모달"}):
    print(token, end="", flush=True)

# 2️⃣ 단일 입력 실행
chain.invoke({"topic": "ChatGPT"})

# 3️⃣ 여러 입력 일괄 실행
chain.batch(
    [
        {"topic": "ChatGPT"},
        {"topic": "Instagram"},
        {"topic": "머신러닝"},
    ],
    config={"max_concurrency": 3},
)

5.2 비동기 체인 - astream / ainvoke/ abatch

비동기(asyncio) 기반으로 동작하며 await 키워드가 필수입니다.

astream은 실제서비스에서 가장 많이 활용되며 abatch로 대량 요청을 동시에 처리할 수 있습니다.

# 비동기 stream
async for token in chain.astream({"topic": "YouTube"}):
    print(token, end="", flush=True)

# 비동기 단일 실행
my_process = chain.ainvoke({"topic": "NVDA"})
await my_process

# 비동기 일괄 실행
await chain.abatch(
    [{"topic": "YouTube"}, {"topic": "Instagram"}, {"topic": "Facebook"}]
)

5.3 병렬 실행 체인 - RunnableParallel

LCEL의 “병렬 실행” 확장 개념을 보여주는 코드로 여러 체인을 동시에 실행하는 구조를 확인할 수 있습니다.

from langchain_core.runnables import RunnableParallel

# 수도를 묻는 체인
chain1 = (
    PromptTemplate.from_template("{country} 의 수도는 어디야?")
    | model
    | StrOutputParser()
)

# 면적을 묻는 체인
chain2 = (
    PromptTemplate.from_template("{country} 의 면적은 얼마야?")
    | model
    | StrOutputParser()
)

# 병렬 실행 체인 구성
combined = RunnableParallel(capital=chain1, area=chain2)

# 병렬 실행
combined.invoke({"country": "대한민국"})

# 병렬 일괄 실행
combined.batch([{"country": "대한민국"}, {"country": "미국"}])

6. Runnable

6.1 Runnable이란?

LCEL의 모든 구성요소는 Runnable 프로토콜을 기반으로 작동합니다.

즉, Prompt, Model, Parser는 모두 Runnable로 취급되며, 공통된 실행 인터페이스(invoke, stream, batch 등)를 공유합니다.

쉽게 말해 “입력을 받아 실행하고 결과를 반환할 수 있는 모든 객체"는 Runnable이라 할 수 있습니다.

6.2 RunnablePassthrough - 입력 그대로 통과 시키기

RunnablePassthrough는 말 그대로 입력값을 가공하지 않고 그대로 다음 단계로 전달하는 Runnable입니다.

LLM 호출 없이 입력 데이터를 확인하거나, 중간 단계 디버깅용으로 자주 사용됩니다.

from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI

# prompt 와 llm 을 생성합니다.
prompt = PromptTemplate.from_template("{num} 의 10배는?")
llm = ChatOpenAI(temperature=0)

# 체인 구성
chain = prompt | llm

# 체인 실행
chain.invoke({"num": 5})
chain.invoke(5)

from langchain_core.runnables import RunnablePassthrough

# RunnablePassthrough은 입력 그대로 반환
RunnablePassthrough().invoke({"num": 10})

# chain 내부에 삽입
runnable_chain = {"num": RunnablePassthrough()} | prompt | ChatOpenAI()
runnable_chain.invoke(10)

6.3 RunnableParallel - 병렬 실행 체인

RunnableParallel은 여러 Runnable을 동시에 실행하는 구조입니다.

입력값을 각 Runnable에 동일하게 전달한 뒤, 결과를 병렬로 받아와 딕셔너리 형태로 반환됩니다.

from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI

# 두 개의 체인을 정의합니다.
chain1 = (
    {"country": RunnablePassthrough()}
    | PromptTemplate.from_template("{country} 의 수도는?")
    | ChatOpenAI()
)
chain2 = (
    {"country": RunnablePassthrough()}
    | PromptTemplate.from_template("{country} 의 면적은?")
    | ChatOpenAI()
)

# RunnableParallel로 병렬 실행 구성
combined_chain = RunnableParallel(capital=chain1, area=chain2)

# 병렬 실행
combined_chain.invoke("대한민국")

6.4 RunnableLambda - 사용자 정의 함수형 체인

RunnableLambda는 파이썬 함수를 Runnable로 감싸는 유틸리티입니다.

사용자 정의 함수를 통해 입력 전처리 또는 동적 데이터 삽입이 가능합니다.

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.runnables import RunnableLambda, RunnablePassthrough
from datetime import datetime

# 오늘 날짜를 반환하는 함수
def get_today(_):
    return datetime.today().strftime("%b-%d")

# 프롬프트 및 모델 구성
prompt = PromptTemplate.from_template(
    "{today} 가 생일인 유명인 {n} 명을 나열하세요. 생년월일을 표기해 주세요."
)
llm = ChatOpenAI(temperature=0, model_name="gpt-4.1-mini")

# 체인 구성
chain = (
    {"today": RunnableLambda(get_today), "n": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

# 실행
print(chain.invoke(3))

참고 자료

https://wikidocs.net/book/14314

<랭체인LangChain 노트> - LangChain 한국어 튜토리얼

**추천**은 공유할 수 있는 무료 전자책을 집필하는데 정말 큰 힘이 됩니다. **"추천"** 한 번씩만 부탁 드리겠습니다 ✅ **랭체인 한국어 튜토리얼 강의** …

wikidocs.net

https://github.com/teddylee777/langchain-kr

GitHub - teddylee777/langchain-kr: LangChain 공식 Document, Cookbook, 그 밖의 실용 예제를 바탕으로 작성한 한

LangChain 공식 Document, Cookbook, 그 밖의 실용 예제를 바탕으로 작성한 한국어 튜토리얼입니다. 본 튜토리얼을 통해 LangChain을 더 쉽고 효과적으로 사용하는 방법을 배울 수 있습니다. - teddylee777/langch

github.com

[Unity] 구글폼 연동해서 데이터를 구글 스프레드시트에 저장하는 방법

orieasy1 — Sun, 28 Sep 2025 23:51:58 +0900

저는 현재 MR 환경에서 사용자 연구를 진행하고 있는데요, 실험을 진행하면서 데이터를 저장해야했습니다.

처음에는 그냥 기기 내에 csv 파일을 저장하는 방향으로 생각했는데 실시간으로 체크해야할 필요성을 느껴서 구글폼과 구글폼에 연동되어있는 스프레드시트로 데이터를 기록하는 방법으로 구현을 진행하였습니다.

그래서 오늘은 구글폼과 스프레드 시트를 이용하여 편하게 Unity 내에서 데이터를 기록하는 방법에 대해 이야기 해보고자 합니다.

1. TaskManager

일단 저는 기능 전반을 관리하는 TaskManager C# 파일이 있었습니다. (전체적인 프로그램 진행 관리)

해당 파일에서 LogCurrentTask()라는 메소드를 사용하여 전반적인 데이터 관리 로직을 구현하였습니다.

처음에는 한 task가 끝날 때마다 해당 메소드를 호출하여 데이터를 csv 파일에 추가하는 방식으로 진행을 했습니다.

구글폼으로 진행하기로 마음을 먹은 뒤에는 GoogleSpreadSheetsManager 이라는 클래스를 새로 만들었습니다.

우선 메인 TaskManager에서 GoogleSpreadSheetsManager에 데이터를 보내주는 로직을 LogCurrentTask() 메소드 안에 작성해줍니다.

void LogCurrentTask(bool success)
    {
        if (_phase == TaskPhase.Practice) return;

        float manipulationTime = (_manipStartTime > 0f) ? (Time.time - _manipStartTime) : 0f;
        float firstGrabToSuccess = (_firstGrabTime > 0f && _successTime > 0f) 
                               ? (_successTime - _firstGrabTime) 
                               : 0f;

        var saver = GetComponent<GoogleFormSaver>();
        if (saver)
        {
            StartCoroutine(saver.PostData(
                participantID,
                _taskIndex + 1,
                manipulationTime,
                _targetEuler.x, _targetEuler.y, _targetEuler.z,
                _finalEuler.x, _finalEuler.y, _finalEuler.z,
                _targetQ.x, _targetQ.y, _targetQ.z, _targetQ.w,
                _finalQ.x, _finalQ.y, _finalQ.z, _finalQ.w,
                _angleDiff,
                _cumObjTotal,
                _cumRightTotal,
                _firstGrabTime,
                _successTime,
                firstGrabToSuccess
            ));
        }
        else
        {
            Debug.LogError("[TaskManager] GoogleFormSaver not found!");
        }
    }

2. GoogleSpreadSheetsManager

이제 구글폼과 우리 프로그램을 연결해줄 GoogleSpreadSheetsManager을 만들 차례입니다.

우선 구글폼을 하나 만들어주시고 응답자용 설문지에 접속합니다.

그후 F12를 누르셔서 elements 창에 들어갑니다.

formResponse를 검색해서 나타나는 url을 복사해주세요!

해당 링크를 복사한 뒤 아래 코드의 링크 부분에 복사해서 넣어줍니다.

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

public class GoogleFormSaver : MonoBehaviour
{
    private string BASE_URL = "링크";

    public IEnumerator PostData(
        string participantID, int taskIndex, float completionTime,
        // 목표 Euler
        float targetX, float targetY, float targetZ,
        // 최종 Euler
        float finalX, float finalY, float finalZ,
        // 목표 Quaternion
        float targetQx, float targetQy, float targetQz, float targetQw,
        // 최종 Quaternion
        float finalQx, float finalQy, float finalQz, float finalQw,
        // Quaternion.Angle 기반 최종 오차
        float angleDiff,
        // 누적 회전량
        float cumObjTotal,
        float cumRightTotal,
        // 추가 항목
        float firstGrabTime,
        float successTime,
        float firstGrabToSuccess
    )
    {
        WWWForm form = new WWWForm();

        // 기본 정보
        form.AddField("entry.1813064294", participantID);               // 1
        form.AddField("entry.2037882169", taskIndex.ToString());        // 2
        form.AddField("entry.800267908", completionTime.ToString());    // 3

        // 목표 Euler
        form.AddField("entry.1055469485", targetX.ToString());          // 4
        form.AddField("entry.507956897", targetY.ToString());           // 5
        form.AddField("entry.1031840251", targetZ.ToString());          // 6

        // 최종 Euler
        form.AddField("entry.1220958015", finalX.ToString());           // 7
        form.AddField("entry.1290950597", finalY.ToString());           // 8
        form.AddField("entry.912135107", finalZ.ToString());            // 9

        // 목표 Quaternion
        form.AddField("entry.1476745007", targetQx.ToString());         // 10
        form.AddField("entry.1084862304", targetQy.ToString());         // 11
        form.AddField("entry.1065111899", targetQz.ToString());         // 12
        form.AddField("entry.905889161", targetQw.ToString());          // 13

        // 최종 Quaternion
        form.AddField("entry.585115881", finalQx.ToString());           // 14
        form.AddField("entry.960417364", finalQy.ToString());           // 15
        form.AddField("entry.1742970737", finalQz.ToString());          // 16
        form.AddField("entry.968201013", finalQw.ToString());           // 17

        // 전체 오차
        form.AddField("entry.779680696", angleDiff.ToString());         // 18

        // 누적 회전량
        form.AddField("entry.1576350621", cumObjTotal.ToString());      // 19
        form.AddField("entry.415742032", cumRightTotal.ToString());     // 20

        // 추가 필드
        form.AddField("entry.1318261917", firstGrabTime.ToString());    // 21
        form.AddField("entry.1960975797", successTime.ToString());      // 22
        form.AddField("entry.1242245653", firstGrabToSuccess.ToString());// 23

        using (UnityWebRequest www = UnityWebRequest.Post(BASE_URL, form))
        {
            yield return www.SendWebRequest();

            if (www.result != UnityWebRequest.Result.Success)
                Debug.LogError("Google Form POST Error: " + www.error);
            else
                Debug.Log("Google Form POST Success!");
        }
    }
}

그리고 위 entry.숫자 부분 보이시나요?

이 부분도 구현하시는 프로그램에 맞추어 변경해주어야합니다!

F12를 눌러 다시 개발자툴창에 접속하고 이번에는 Network에 접속해주세요. 그리고 임으로 만든 폼을 제출합니다.

그럼 이렇게 뜨게 되는데요. 여기서 formResponse를 클릭해주세요.

Payload 를 클릭하면 Form Data를 볼 수 있습니다. 해당 entry들을 코드 안에 작성해주면 완성입니다.

그후 유니티 Scene에서 TaskManager가 연결되어있는 오브젝트에 구글폼 컴포넌트를 추가하는 것 잊지말아주세요!

프로그램을 실행시키고 구글폼과 연결된 스프레드시트를 확인하면

이렇게 데이터가 잘 들어오는 것을 확인할 수 있습니다!

CSV를 활용하는 것도 좋지만 구글폼을 사용할 경우 실시간으로 업데이트 되는 것을 확인할 수 있어서 굉장히 편했습니다!!

유니티를 이용해 데이터 수집을 할 때 참고해서 진행하시면 좋을 것 같습니다!

Unity로 Meta Quest3 MR(Passthrough) 빌드하기

orieasy1 — Fri, 19 Sep 2025 22:59:57 +0900

요즘 연구실에서 Passthrough 관련 연구를 진행하고 있어서 user study를 진행할 프로그램을 만들고 있다.

그래서 오늘은 Meta Ques 3을 기준으로 Unity로 MR 프로그램을 빌드하는 법을 소개하려고 한다.

1. Unity 설정

우선 다운로드 받은 Unity Editor에 Android Build Support과 관련된 모듈을 다운받아 줍니다.

그리고 Edit > Project Setting > XR Plugin Management를 접속하여 해당 plugin management도 다운 받아줍니다.

그리고 OpenXR에 체크 표시를 해줍니다.

그러면 아래 사진과 같이 fix 해야할 것들이 많다고 뜰 것이다.

모두 Fix All 처리를 해주면 된다.

이제 Meta Quest build platform을 설정해줄 차례이다.

File > Build Profiles로 접속한 뒤 Android에서 Switch Platform을 클릭하여 Platform을 전환 시켜준다.

이후 나는 Meta XR Interaction SDK를 다운받아서 사용하였다.

https://assetstore.unity.com/packages/tools/integration/meta-xr-interaction-sdk-265014

Meta XR Interaction SDK | 기능 통합 | Unity Asset Store

Use the Meta XR Interaction SDK from Meta on your next project. Find this integration tool & more on the Unity Asset Store.

assetstore.unity.com

또 우측 상단에 위치한 Meta XR Tools에 들어가서 주기적으로 Fix all 처리를 해주어야 한다.

2. 빌드 시 체크포인트

MR 콘텐츠를 제작 후 빌드할 예정이라면 체크해야할 부분이 몇 가지 있다.

example scenes 각 Scene의 OVRCameraRig에서 OVRManager > passthrough 옵션이 켜졌는지 확인해야한다.

사진에서처럼 .Supported로 표시되어야 한다.

두 번째, OVRCameraRig에 OVRPassthroughLayer 추가해야 한다.

Inspector 하단의 Add Component를 클릭한 뒤 서치하여 추가하면 된다.

그리고 Placement 조건을 Underlay로 선택한다.

마지막은 Skybox를 제거하는 것이다.

Window > Rendering > Lighting > Environment로 이동하여 Skybox Material에서의 SkyboxGradient를 삭제해야 한다.

사진처럼 None이 뜨면 삭제가 된 것이다.

3. Meta Quest 3 연결 확인

빌드를 하기 전에 기기가 컴퓨터에 잘 연결되었는지도 확인해야 한다.

우산 아래 링크로 접속하여 adb를 다운받아야 한다. (설치가 안되어있는 경우)

https://developer.android.com/tools/releases/platform-tools?hl=ko

SDK 플랫폼 도구 출시 노트 | Android Studio | Android Developers

Android SDK 플랫폼 도구는 Android SDK의 구성요소입니다.

developer.android.com

다운받은 후 환경 변수를 설정해주면 좀 더 편하게 사용할 수 있다.

시스템 변수 목록에서 Path을 선택하여 아까 확인한 platform-tools 경로(다운로드 받은 파일 압축을 푼 위치)를 입력해주면 된다.

이후 cmd창을 열어 잘 설정되었는지 확인해주자.

첫 번째처럼 unauthorized라고 뜬다면 헤드셋 안에서 USB 디버깅 허용 팝업을 확인하고 허용을 눌러야 한다.

두 번째처럼 기기 번호가 뜬다면 연결 성공이다.

이후 Meta Quest 기기 를 연결한 상태로 build and run을 실행하며 passthrough 프로그램을 즐길 수 있다.