专栏名称: 前端早读课
我们关注前端,产品体验设计,更关注前端同行的成长。 每天清晨五点早读,四万+同行相伴成长。
目录
相关文章推荐
前端大全  ·  前端中的 File 和 ... ·  3 天前  
前端早读课  ·  【第3414期】提升ServiceWorke ... ·  3 天前  
光伏资讯  ·  光伏企业苦展览久矣! ·  5 天前  
前端早读课  ·  【第3413期】2024年CSS状态调查报告 ·  5 天前  
前端大全  ·  放弃 React,微软 Edge 团队改用 ... ·  6 天前  
51好读  ›  专栏  ›  前端早读课

【早阅】代码注释自动化:使用 VS Code 和 Ollama

前端早读课  · 公众号  · 前端  · 2024-11-13 08:00

正文

.作者:@Carlos Mucuho
原文:https://blog.logrocket.com/automate-code-commenting-using-vs-code-ollama/

概述

在软件开发中,代码注释扮演着至关重要的角色。它们不仅解释复杂的逻辑,记录决策过程,还为未来的开发者提供上下文信息。尽管有人认为编写良好的代码应该是自解释的,但其他人强调注释在捕捉特定实现背后的推理方面的重要性。随着 AI 驱动的编码助手如 GitHub Copilot 的流行,自动化注释生成的想法引发了关于 AI 是否能真正捕捉到使注释有价值的人类洞察力的讨论。

【第3252期】Ollama:本地大模型运行指南

本文介绍如何构建一个 VS Code 扩展程序,利用 Ollama.js 库和本地大型语言模型 (LLM) 自动生成程式码注释。Ollama 本身不是一个编程助手,而是一个允许开发人员运行大型语言模型 (LLM) 以提高生产力的工具,通过本教程,您将学习如何利用 AI 编码工具简化文档流程,而无需共享您的数据或支付昂贵的订阅费用。

最终呈现的效果:

一、Ollama 设置

1、下载并安装 Ollama:根据您的操作系统从 Ollama 官方网站下载相应的安装程序。

  • 要在 Windows 上安装 Ollama,请下载可执行文件并运行它。Ollama 将自动安装,您就可以开始使用它了。

  • 对于 Mac,在下载 Ollama for MacOS 后,解压文件并将 Ollama.app 文件夹拖到您的 Applications 文件夹中。移动应用程序后,安装就完成了。

  • 对于 Linux 用户,安装 Ollama 就像在您的终端中运行以下命令一样简单:

 curl -fsSL https://ollama.com/install.sh | sh

2、启动 Ollama 服务:打开 Ollama 应用程序或在终端中运行 ollama serve 命令。

Ollama 安装完成后,您可以开始与 LLM 进行交互。在运行任何命令之前,您需要通过打开应用程序或在终端中运行以下命令来启动 Ollama:

 ollama serve

此命令启动 Ollama 应用程序,允许您使用可用的命令。它还启动在端口 11434 上运行的 Ollama 服务器。您可以通过打开一个新的浏览器窗口并导航到 http://localhost:11434/ 来检查服务器是否正在运行。

3、获取和运行模型:使用 ollama pull 命令获取模型,并使用 ollama run 命令运行模型。

要从 Ollama 注册表中拉取模型而不运行它,请使用 ollama pull 命令。例如,要拉取 phi3.5 模型,请运行以下命令:

 ollama pull phi3.5

此命令获取模型并使其可供以后使用。

您可以使用以下命令列出所有已拉取的模型:

 ollama list

这将显示模型列表及其大小和修改时间:

 NAME ID SIZE MODIFIED

phi3.5:latest 61819fb370a3 2.2 GB 11 days ago

llava:latest 8dd30f6b0cb1 4.7 GB 2 weeks ago

phi3:latest 64c1188f2485 2.4 GB 3 months ago

csfm1993:~$

要立即拉取和执行模型,请使用 ollama run 命令。例如,要运行 phi3.5,请运行:

 ollama run phi3.5

此命令拉取模型(如果尚未拉取),并开始执行,以便您可以立即开始查询它。

您应该在您的终端中看到以下内容:

 csfm1993:~$ ollama run phi3.5

>>> Send a message (/? for help)
>>>

在本教程中,您将使用 phi3.5 模型为给定的程式码块生成注释。选择这种语言模型是因为它在大小和性能之间取得了平衡 —— 虽然它很紧凑,但它提供了强大的结果,使其成为构建概念验证应用程序的理想选择。

phi3.5 模型足够轻巧,可以在 RAM 有限且没有 GPU 的计算机上高效运行。如果您有 GPU,请随时运行更大的 LLM。

将以下提示发送到模型:

 complete code: " const express = require('express') const app = express() const port = 3000 app.get('/', (req, res) => { res.send('Hello World!') }) 
app.listen(port, () => { console.log(`Example app listening on port ${port}`) }) " Given the code block below, write a brief, insightful comment that explains
its purpose and functionality within the script. If applicable, mention any inputs expected in the code block. Keep the comment concise (maximum 2 lines). Wrap
the comment with the appropriate comment syntax (//). Avoid assumptions about the complete code and focus on the provided block. Don't rewrite the code block.
code block: " app.get('/', (req, res) => { res.send('Hello World!') }) "

提示要求 phi3.5 模型解释给定程式码块中发生的事情。您应该得到类似于以下的答案:

 // This Express.js route handler responds to GET requests at the root URL ('/'), sending back a plain text 'Hello World!' message as an HTTP response. No 
additional inputs are required for this specific block of code, which serves as a basic setup example within a web server context.

模型返回一个带有指定注释语法的注释,后面是解释。与模型交互完成后,发送命令 /bye 结束聊天。

本教程使用 phi3.5 模型生成注释,它体积小、性能强,适合构建概念验证应用程序。

二、创建和配置项目

1、使用 Yeoman 和 VS Code Extension Generator 创建一个新的 VS Code 扩展程序项目。

 npx --package yo --package generator-code -- yo code

建立一个新的 VS Code 扩展程序项目。你需要选择 TypeScript 作为项目语言,并填写其他必要的字段,例如扩展程序名称、标识符和描述等。

2、使用 npm install ollama cross-fetch 命令安装必要的模块。

 npm install ollama cross-fetch

安装与 Ollama 服务器交互所需的模块:

  • ollama: 提供与大型语言模型(LLM)互动的工具和实用程序,用于与 Ollama 伺服器通讯并发送提示以生成代码注释。

  • cross-fetch: 为 Node.js 带来 Fetch API 支持,允许在原生不支持 Fetch 的环境中获取资源,例如 API 请求。用于向 Ollama 服务器发出 HTTP 请求,避免 LLM 生成响应时间过长导致的 HTTP 请求超时错误。

3、在 package.json 文件中,确保 vscode 版本与您系统中安装的 VS Code 版本匹配。

 "engines": {
"vscode": "你的 VS Code 版本"
},

在 package.json 中,找到 engines 属性,并将 vscode 的值设置为你系統中安裝的 VS Code 版本。

4、将默认的 "Hello World" 命令替换为 "Generate Comment" 命令。

 "contributes": {
"commands": [
{
"command": "commentgenerator.generateComment",
"title": "Generate Comment"
}
]
},

在 package.json 中,找到 contributes.commands 部分,将原来的 "Hello World" 命令替换为 "Generate Comment" 命令,并将其 ID 设置为 commentgenerator.generateComment。

打开 extension.ts 文件,将 activate 函数内的代码替换为以下代码:

 import * as vscode from 'vscode';
export function activate(context: vscode.ExtensionContext) {
console.log('Congratulations, your extension "commentgenerator" is now active!');

const generateCommentCommand = vscode.commands.registerCommand('commentgenerator.generateComment', async () => {
vscode.window.showInformationMessage('Generating comment, please wait');
});

context.subscriptions.push(generateCommentCommand);
}


5、使用 npm run watch 命令监控项目更改并自动编译。

 npm run watch

在终端中运行此命令,启动 TypeScript 编译器的监控模式。它会在你修改项目文件时自动重新编译项目。

三、构建提示

1、使用 getScriptContext 函数获取当前文件的完整内容作为代码上下文。

 import * as vscode from 'vscode';

/**
* 获取当前文件的完整文本作为代码上下文。
* @param editor 当前文本编辑器。
* @returns 代码上下文。
*/

function getScriptContext(editor: vscode.TextEditor): string {
const document = editor.document;
const codeContext = document.getText();
return codeContext;
}

2、使用 getCodeBlock 函数从剪贴板中读取代码块。

 /**
* 从剪贴板中读取代码块。
* @returns 代码块。
*/

async function getCodeBlock(): Promise<string> {
const codeBlock = await vscode.env.clipboard.readText();
return codeBlock;
}

3、使用 selectCommentSyntax 函数根据文件扩展名选择适当的注释语法。

 /**
* 根据文件扩展名选择适当的注释语法。
* @param editor 当前文本编辑器。
* @returns 注释语法。
*/

function selectCommentSyntax(editor: vscode.TextEditor): string {
const fileExtension = editor.document.fileName.toLowerCase().split('.').at(-1);
const commentSyntax = fileExtension === 'js' ? '//' : '#';
return commentSyntax;
}

4、使用 buildPrompt 函数构建提示字符串,该字符串包含代码块、代码上下文和注释语法,并指示 LLM 生成简洁、深刻的注释。

 /**
* 构建提示字符串。
* @param editor 当前文本编辑器。
* @returns 提示字符串。
*/

export async function buildPrompt(editor: vscode.TextEditor): Promise<string> {
const codeBlock = await getCodeBlock();
const codeContext = getScriptContext(editor);
const commentSyntax = selectCommentSyntax(editor);

if (codeBlock === undefined || codeContext === undefined) {
return;
}

let prompt = `
complete code: "{CONTEXT}"
Given the code block below, write a brief, insightful comment that explains its purpose and functionality within the script. If applicable, mention any inputs
expected in the code block. Keep the comment concise (maximum 2 lines). Wrap the comment with the appropriate comment syntax ({COMMENT-SYNTAX}). Avoid
assumptions about the complete code and focus on the provided block. Don't rewrite the code block.
code block: "{CODE-BLOCK}"
`;

prompt = prompt
.replace('{CONTEXT}', codeContext)
.replace('{CODE-BLOCK}', codeBlock)
.replace('{COMMENT-SYNTAX}', commentSyntax);

return prompt;
}

四、使用 Ollama.js 生成注释

1、使用 Ollama 类创建一个新的 Ollama 实例,并指定主机和 fetch 函数。

 import { Ollama } from 'ollama';
import fetch from 'cross-fetch';

// 创建一个新的 Ollama 实例,指定主机和 fetch 函数
const ollama = new Ollama({
host: 'http://127.0.0.1:11434',
fetch: fetch,
});

2、使用 generateComment 函数发送提示到 Ollama 服务器并接收生成的注释。

3、使用 performance.now 函数记录 LLM 生成响应所需的时间。

 /**
* 发送提示到 Ollama 服务器并接收生成的注释。
* @param prompt 提示字符串。
* @returns 生成的注释。
*/

export async function generateComment(prompt: string): Promise<string> {
// 记录开始时间
const t0 = performance.now();

// 发送请求到 Ollama 服务器
const req = await ollama.generate({
model: 'phi3.5', // 使用 phi3.5 模型
prompt: prompt,
});

// 记录结束时间
const t1 = performance.now();

// 计算 LLM 生成响应所需的时间
console.log('LLM took: ', t1 - t0, ', seconds');

// 返回生成的注释
return req.response;
}

五、将注释添加到脚本

1、使用 getCurrentLine 函数获取当前行号。

 import * as vscode from 'vscode';

/**
* 获取当前行号。
* @param editor 当前文本编辑器。
* @returns 当前行号。
*/

export function getCurrentLine(editor: vscode.TextEditor): number {
const currentLine = editor.selection.active.line;
console.log('currentLine: ', currentLine);
return currentLine;
}

2、使用 addCommentToFile 函数将生成的注释添加到指定行。

3、使用 WorkspaceEdit 对象插入注释,并使用 applyEdit 函数应用编辑。

 /**
* 将生成的注释添加到指定行。
* @param fileURI 文件 URI。
* @param fileName 文件名。
* @param line 行号。
* @param generatedComment 生成的注释。
*/

export async function addCommentToFile(
fileURI: vscode.Uri,
fileName: string,
line: number,
generatedComment: string,

): Promise<void> {
console.log('adding comment', line, generatedComment);

// 创建一个新的 WorkspaceEdit 对象
const edit = new vscode.WorkspaceEdit();

// 使用 insert 方法将注释插入到指定位置
edit.insert(fileURI, new vscode.Position(line, 0), generatedComment.trim());

// 应用编辑
await vscode.workspace.applyEdit(edit);

// 显示信息消息
vscode.window.showInformationMessage(`已将注释添加到 ${fileName} 的第 ${line + 1}`);

整个插件代码,请看原文代码片段,特别是extension.ts文件的。

结论

本教程演示了如何使用 VS Code 和 Ollama 构建一个自动化代码注释的扩展程序。这个项目展示了如何在不共享数据或支付昂贵订阅费用的情况下,利用 LLM 模型提高生产力。

AI 阅:了解技术资讯的一种方式。

🚀可直接通过阅读原文了解详细内容。